Extending WP Contacts

You are here:
Read time: 7 min

WP Contacts includes many features that allow you to extend it for use with other applications and tools. We also include hooks and filters for easy access to developers in modifying output and behavior.

Zapier extension for WP Contacts

We now have an extension available for WP Contacts to allow you to integrate with Zapier.com. Zapier lets you integrate with over 750 popular applications (such as Gmail, Slack, MailChimp…many more).  Have a look at our Zapier documentation to learn more!

WP Contacts REST – Version 1

Starting with version 3.0 and above of WP Contacts we have greatly expanded the capability for users to tie in other applications using the WordPress REST api and our custom endpoints.  This opens the doors to all sorts of possibilities with WP Contacts, for example having a form submitted on another site (e.g. www.yoursite1.com) can send the information to create that contact in your WP Contacts database (e.g. www.yoursite2.com).  Or, if an entry is created in WP Contacts, you can for example send a notification to an email address or any other tool that can work with REST (or uses Webhooks).

Obviously, some understanding of REST API’s, authentication, and SSL are going to be necessary for implementing a service like this.  While a REST service provides the means for communication between applications, it is up you to either have the knowledge or resources to implement this functionality.  Support for these items functioning correctly on your site is well beyond WP Contacts support.  Although, if you open a ticket for customization help and we have the resources at the time, we can offer assistance for a fee.

WordPress itself has built-in endpoints but we actually add our own as well which are listed below.  Be sure to take a look at WordPress’s documentation on using the api https://developer.wordpress.com/docs/api/ .  You’ll also want to use some form of Authentication as well and you have at least 3 choices on your approach:

  • Basic Authentication or Application Passwords
  • OAuth1a
  • OAuth2

Here is a resource that explains these as well http://v2.wp-api.org/guide/authentication/ .  For OAuth2, here is a plugin that provides a server for authentication – https://wordpress.org/plugins/oauth2-provider/ .

WordPress version 4.7+ includes the REST API in core, so you won’t need to install anything extra for that functionality.  What you probably will want to do is add authentication and more than likely encrypt communications by using an ssl certificate on your website (https) and have your applications only communicate over https.  Oauthv1 is about the only recommended method for unencrypted communication with the WordPress API but it’s currently the most difficult to get running.  At the end of the day, these decisions are all yours to make as to how you authenticate with your WordPress installation.

Requirements for using the WordPress REST API with WP Contacts are as follows:

  • Running WordPress version 4.7+ (or you’ve installed the WordPress REST API plugin for previous versions – highly recommended to be running the latest version of WordPress though).
  • Running version 3.0+ of WP Contacts for this functionality to be included
  • Authentication is required (choices listed in the introduction) and the authenticated user must be a WordPress Admin to access our endpoints
  • PHP version 5.5+ recommended and required for some of the authentication plugins listed above (OAuth2 Server)
  • The ability for your website to send and receive POST and GET http requests from another API
  • Required –  “pretty” permalinks enabled. Please ensure that the permalink setting is NOT set to the default (http://mydomain.com/?p=123) before trying to use the API. Any setting other than the default will be fine.
  • Highly recommended to use https for endpoints and hooks – to protect against usernames, passwords, tokens etc. being intercepted by a third party

REST Endpoints (11 total)

 Ping – GET

endpoint: /wp-json/shwcp/v1/ping/

params

  1. none

https://yoursite.com/wp-json/shwcp/v1/ping

successful response

{
    "auth": true
}

description: Simple authentication verification endpoint

Total Count – GET

endpoint: /wp-json/shwcp/v1/get-entry-count/

params

  1. db (optional) – database name

https://yoursite.com/wp-json/shwcp/v1/get-entry-count/?db=Contacts3

successful response

{
  "count": "2",
  "database": "Contacts3",
  "database_number": "_2"
}

description: Returns the total entry count (“count”) in the database.  Requests will go to the default database unless another is specified.

Get Entries – GET

endpoint: /wp-json/shwcp/v1/get-entries/

params

  1. db (optional) – database name
  2. first (optional) – starting number
  3. limit (optional) – limit 50 results etc.

https://yoursite.com/wp-json/shwcp/v1/get-entries?db=default&first=1&limit=2

successful response

{
  "entries": [
    {
      "first_name": {
        "value": "Jim",
        "trans": "First Name"
      },
      "last_name": {
        "value": "Johnson",
        "trans": "Last Name"
      },
      "extra_column_1": {
        "value": "Option 1",
        "trans": "dropdown"
      },
      "extra_column_2": {
        "value": "4",
        "trans": "Rating"
      },
      "extra_column_3": {
        "value": "0",
        "trans": "Checkbox"
      },
      "extra_column_4": {
        "value": "",
        "trans": "Group Title"
      },
      "created_by": {
        "value": "sh-themes",
        "trans": "Created By"
      },
      "creation_date": {
        "value": "2016-12-09 17:53:10",
        "trans": "Created"
      },
      "updated_by": {
        "value": "sh-themes",
        "trans": "Updated By"
      },
      "updated_date": {
        "value": "2017-01-02 18:08:43",
        "trans": "Updated"
      },
      "l_source": {
        "value": "Default",
        "trans": "Source"
      },
      "l_status": {
        "value": "Default",
        "trans": "Status"
      },
      "l_type": {
        "value": "Default",
        "trans": "Type"
      },
      "owned_by": {
        "value": "sh-themes",
        "trans": "Owned By"
      },
      "id": {
        "value": "2",
        "trans": "ID"
      },
      "small_image": {
        "value": "http://php56host.com/plugins/wp-content/uploads/shwcp/2-small_image.png",
        "trans": "small_image"
      },
      "lead_files": {
        "value": "",
        "trans": "lead_files"
      },
      "notes": [
        {
          "id": "3",
          "note_content": "<p>Note 3</p>",
          "date_added": "2016-12-11 21:17:16",
          "creator": "sh-themes",
          "date_updated": "0000-00-00 00:00:00"
        },
        {
          "id": "3",
          "note_content": "<p>Note 3</p>",
          "date_added": "2016-12-11 21:17:16",
          "creator": "scripthat",
          "date_updated": "0000-00-00 00:00:00"
        },
        {
          "id": "3",
          "note_content": "<p>Note 3</p>",
          "date_added": "2016-12-11 21:17:16",
          "creator": "jimmy",
          "date_updated": "0000-00-00 00:00:00"
        }
      ]
    },
    {
      "first_name": {
        "value": "testeriif",
        "trans": "First Name"
      },
      "last_name": {
        "value": "test",
        "trans": "Last Name"
      },
      "extra_column_1": {
        "value": "Option Created Again",
        "trans": "dropdown"
      },
      "extra_column_2": {
        "value": "0",
        "trans": "Rating"
      },
      "extra_column_3": {
        "value": "0",
        "trans": "Checkbox"
      },
      "extra_column_4": {
        "value": "",
        "trans": "Group Title"
      },
      "created_by": {
        "value": "sh-themes",
        "trans": "Created By"
      },
      "creation_date": {
        "value": "2017-01-02 16:20:31",
        "trans": "Created"
      },
      "updated_by": {
        "value": "sh-themes",
        "trans": "Updated By"
      },
      "updated_date": {
        "value": "2017-01-02 17:31:09",
        "trans": "Updated"
      },
      "l_source": {
        "value": "Source 1",
        "trans": "Source"
      },
      "l_status": {
        "value": "Status 1",
        "trans": "Status"
      },
      "l_type": {
        "value": "Type 1",
        "trans": "Type"
      },
      "owned_by": {
        "value": "sh-themes",
        "trans": "Owned By"
      },
      "id": {
        "value": "89",
        "trans": "ID"
      },
      "small_image": {
        "value": "http://php56host.com/plugins/wp-content/uploads/shwcp/89-small_image.png",
        "trans": "small_image"
      },
      "lead_files": {
        "value": [],
        "trans": "lead_files"
      },
      "notes": [
        {
          "id": "6",
          "note_content": "<p>testing adding a note</p>",
          "date_added": "2017-01-02 17:12:58",
          "creator": "sh-themes",
          "date_updated": "0000-00-00 00:00:00"
        },
        {
          "id": "6",
          "note_content": "<p>testing adding a note</p>",
          "date_added": "2017-01-02 17:12:58",
          "creator": "scripthat",
          "date_updated": "0000-00-00 00:00:00"
        },
        {
          "id": "6",
          "note_content": "<p>testing adding a note</p>",
          "date_added": "2017-01-02 17:12:58",
          "creator": "jimmy",
          "date_updated": "0000-00-00 00:00:00"
        },
        {
          "id": "8",
          "note_content": "<p>testing one more time with note id and some formatting</p>\n<ol>\n<li>test</li>\n<li>tester</li>\n<li>testing</li>\n<li>testery</li>\n</ol>",
          "date_added": "2017-01-02 17:15:32",
          "creator": "sh-themes",
          "date_updated": "2017-01-02 17:18:19"
        },
        {
          "id": "8",
          "note_content": "<p>testing one more time with note id and some formatting</p>\n<ol>\n<li>test</li>\n<li>tester</li>\n<li>testing</li>\n<li>testery</li>\n</ol>",
          "date_added": "2017-01-02 17:15:32",
          "creator": "scripthat",
          "date_updated": "2017-01-02 17:18:19"
        },
        {
          "id": "8",
          "note_content": "<p>testing one more time with note id and some formatting</p>\n<ol>\n<li>test</li>\n<li>tester</li>\n<li>testing</li>\n<li>testery</li>\n</ol>",
          "date_added": "2017-01-02 17:15:32",
          "creator": "jimmy",
          "date_updated": "2017-01-02 17:18:19"
        }
      ]
    }
  ],
  "database": "default",
  "database_number": "",
  "request": {
    "db": "default",
    "first": "1",
    "limit": "2"
  }
}

description: Returns multiple entries from the database.  Response contains “entries” array with field original name array containing value and translated name.  Requests will go to the default database unless another is specified

Get Single Entry – GET

endpoint: /wp-json/shwcp/v1/get-entry/

params

  1. db (optional) – Database name
  2. field – real field name (e.g. first_name)
  3. val – matching value

https://yoursite.com/wp-json/shwcp/v1/get-entry?field=id&val=2

successful response

{
  "entry": {
    "first_name": {
      "value": "Jim",
      "trans": "First Name"
    },
    "last_name": {
      "value": "Johnson",
      "trans": "Last Name"
    },
    "extra_column_1": {
      "value": "Option 1",
      "trans": "dropdown"
    },
    "extra_column_2": {
      "value": "4",
      "trans": "Rating"
    },
    "extra_column_3": {
      "value": "0",
      "trans": "Checkbox"
    },
    "extra_column_4": {
      "value": "",
      "trans": "Group Title"
    },
    "created_by": {
      "value": "sh-themes",
      "trans": "Created By"
    },
    "creation_date": {
      "value": "2016-12-09 17:53:10",
      "trans": "Created"
    },
    "updated_by": {
      "value": "sh-themes",
      "trans": "Updated By"
    },
    "updated_date": {
      "value": "2017-01-02 18:08:43",
      "trans": "Updated"
    },
    "l_source": {
      "value": "Default",
      "trans": "Source"
    },
    "l_status": {
      "value": "Default",
      "trans": "Status"
    },
    "l_type": {
      "value": "Default",
      "trans": "Type"
    },
    "owned_by": {
      "value": "sh-themes",
      "trans": "Owned By"
    },
    "id": {
      "value": "2",
      "trans": "ID"
    },
    "small_image": {
      "value": "http://php56host.com/plugins/wp-content/uploads/shwcp/2-small_image.png",
      "trans": "small_image"
    },
    "lead_files": {
      "value": "",
      "trans": "lead_files"
    },
    "notes": [
      {
        "id": "3",
        "note_content": "<p>Note 3</p>",
        "date_added": "2016-12-11 21:17:16",
        "creator": "sh-themes",
        "date_updated": "0000-00-00 00:00:00"
      },
      {
        "id": "3",
        "note_content": "<p>Note 3</p>",
        "date_added": "2016-12-11 21:17:16",
        "creator": "scripthat",
        "date_updated": "0000-00-00 00:00:00"
      },
      {
        "id": "3",
        "note_content": "<p>Note 3</p>",
        "date_added": "2016-12-11 21:17:16",
        "creator": "jimmy",
        "date_updated": "0000-00-00 00:00:00"
      }
    ]
  },
  "database": ""
}

description: Returns a single entry from the database.  Field param must match the internal naming convention (e.g. first_name).  A valid request will give a response with the field original name containing value and translated field name.  Requests will go to the default database unless another is specified

Get Entry Fields – GET

endpoint: /wp-json/shwcp/v1/get-entry-fields/

params

  1. db (optional) – Database name

https://yoursite.com/wp-json/shwcp/v1/get-entry-fields

Successful Response

{
  "first_name": "First Name",
  "last_name": "Last Name",
  "extra_column_1": "dropdown",
  "extra_column_2": "Rating",
  "extra_column_3": "Checkbox",
  "extra_column_4": "Group Title",
  "created_by": "Created By",
  "creation_date": "Created",
  "updated_by": "Updated By",
  "updated_date": "Updated",
  "l_source": "Source",
  "l_status": "Status",
  "l_type": "Type",
  "owned_by": "Owned By",
  "id": "ID",
  "small_image": "Small Image",
  "lead_files": "Entry Files"
}

description: Returns the field name tranlations from the database.  This lists the field name translations with the actual field name mapped to the translated name.  Requests will go to the default database unless another is specified


List Databases – GET

/wp-json/shwcp/v1/list-dbs/

params

  1. none

https://yoursite.com/wp-json/shwcp/v1/list-dbs

successful response

{
  "databases": {
    "1": "Contacts 2",
    "2": "Contacts3",
    "default": "Main Contacts"
  }
}

description: Returns all current WP Contacts databases you have configured.  Default is the main/original database.


Delete Entry – POST

endpoint: /wp-json/shwcp/v1/delete-entry/

params

  1. db (optional) – Database name
  2. id – id of entry to delete

https://yoursite.com/wp-json/shwcp/v1/delete-entry?id=97

successful response

{
  "id": "97",
  "action": "delete",
  "status": 1
}

description:  Deletes WP Contacts entry by id.  Requests will go to the default database unless another is specified


Create Entry – POST

endpoint: /wp-json/shwcp/v1/create-entry/

params

  1. db (optional) – Database name
  2. fields (array) – Field name / value pairs

https://yoursite.com/wp-json/shwcp/v1/create-entry?fields[first_name]=James&fields[last_name]=Smith

successful response

{
  "id": 100,
  "action": "add",
  "fields": {
    "first_name": "James",
    "last_name": "Smith"
  }
}

description: Creates a new entry in WP Contacts with the matching fields sent in the fields param.  Note that field names need to be in the internal name format (e.g. first_name) not the translated name.  Requests will go to the default database unless another is specified


Update Entry – POST

endpoint: /wp-json/shwcp/v1/update-entry/

params

  1. db (optional) – Database name
  2. fields (array) – Field name / value pairs
  3. id – entry id to update

https://yoursite.com/wp-json/shwcp/v1/update-entry?id=100&fields[first_name]=Jim&fields[last_name]=Smith

successful response

{
  "id": 100,
  "action": "update",
  "fields": {
    "first_name": "Jim",
    "last_name": "Smith"
  }
}

description: Updates an existing entry with the fields given in the fields array.  Field names need to match internal naming convention (e.g. first_name).  Requests will go to the default database unless another is specified


Create Entry Note

endpoint: /wp-json/shwcp/v1/create-entry-note

params

  1.  db (optional) – Database name
  2.  id – the entry id that the note relates to
  3.  content – the content of the note

https://yoursite.com/wp-json/shwcp/v1/create-entry-note?id=11&content=testing

successful response

{
    "id": 11,
    "note_id": 17,
    "note_content": "testing"
}

description: Creates a new note entry in WP Contacts that is linked to an entry.  Note that you will need the entry id in the request.  Requests will go to the default database unless another is specified


User Permissions – POST

endpoint: /wp-json/shwcp/v1/user-perms/

params

  1. username – WordPress username
  2. access – choices are ‘none’,’readonly’,’ownleads’,’full’

https://yoursite.com/wp-json/shwcp/v1/user-perms?access=ownleads&username=scripthat

successful response

{
  "status": "Permission Set",
  "userID": 2
}

description: Updates or sets a User’s access for WP Contacts.  Note that the WordPress user needs to exist before their access can be set for WP Contacts.


Upload Entry File – POST

endpoint: /wp-json/shwcp/v1/create-entry-file/

params

  1. db (optional) – Database name
  2. id – entry id to upload file to

https://yoursite.com/wp-json/shwcp/v1/create-entry-file?id=5&db=contacts2

successful response

{
  "status": "File Uploaded",
  "name": "bobsfile.zip",
  "url": "http:/yoursite.com/wp-content/uploads/shwcp/bobsfile.zip",
  "type": "application/x-www-form-urlencoded"
}

description: Uploads a file to the corresponding entry.  Note that the Entry must exist before uploading a file and the http POST must use the correct convention to send the file for WordPress…Be sure you have the Content-Disposition set correctly along with the filename and include your file in the body as binary.  The example below is using basic authentication.

 

POST https://yoursite.com/wp-json/shwcp/v1/create-entry-file?id=2 HTTP/1.1
Host: yoursite.com
Authorization: Basic c2gtdGhlbWVzOnNsdWFnbvm9u
Content-Type: application/x-www-form-urlencoded
Content-Disposition: attachment; filename=bobsfile.zip

Update Entry Image – POST

endpoint: /wp-json/shwcp/v1/update-entry-image/

params

  1. db (optional) – Database name
  2. id – entry id to upload file to

https://yoursite.com/wp-json/shwcp/v1/update-entry-image?id=5&db=contacts2

successful response

 

{
  "status": "Image uploaded",
  "name": "/var/www/html/yoursite/wp-content/uploads/shwcp/2-small_image.jpg",
  "type": "application/x-www-form-urlencoded"
}

description: Uploads an image to the corresponding entry.  Note that the Entry must exist before uploading an image and the http POST must use the correct convention to send the file for WordPress…Be sure you have the Content-Disposition set correctly along with the filename and include your file in the body as binary.  The example below is using basic authentication.

 

POST https://yoursite.com/wp-json/shwcp/v1/update-entry-image?id=2 HTTP/1.1
Host: yoursite.com
Authorization: Basic c2gtdGhlbWVzOnNsdWFnbvm9u
Content-Type: application/x-www-form-urlencoded
Content-Disposition: attachment; filename=blog1.jpg
Was this article helpful?
Dislike 0
Views: 401
Previous: Field Types
Next: Rest Hooks
Join Our Mailing List!