Retrieves a collection of contact records from the CMS API v2.4 based on the supplied parameters.
| Method | URL |
|---|---|
GET |
/v2/contacts |
| Response format | JSON |
| Paginated? | Yes (more information) |
| Rate Limited? | Yes (more information) |
This API endpoint supports the following request parameters:
| Parameter | Description | Notes | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| api_id | The api_id is given to you with your access credentials. |
Required | |||||||||||||||||||||||||||||||||
| data | The URL encoded JSON data string of search parameters. | Required | |||||||||||||||||||||||||||||||||
| sig | The HMAC signature for this request. | Required | |||||||||||||||||||||||||||||||||
| attach |
Comma-separated list of additional related records to be provided with each contact. Current options:
Each related course record will have the following fields:
|
||||||||||||||||||||||||||||||||||
| end_date | Only return records that were updated on or before this date. Dates must be formatted in the following format: YYYY-MM-DD HH:MM. |
||||||||||||||||||||||||||||||||||
| fields |
A URL encoded JSON string of fields that should be included with the response. If fields are not included then the CMS API v2.4 will use a default set of fields. For example: {
"contact" : [
"forenames",
"surname",
"known_as_forenames"
]
}
To retrieve a list of available fields the CMS API v2.4 supports, please refer to the following API endpoint: |
||||||||||||||||||||||||||||||||||
| limit | The number of records to return. The default is 100 records. The maximum records you can return in one response is 1000. | ||||||||||||||||||||||||||||||||||
| offset | The number of rows to skip before beginning the returned rows. | ||||||||||||||||||||||||||||||||||
| start_date | Only return records that were updated on or after this date. Dates must be formatted in the following format: YYYY-MM-DD HH:MM. |
https://cmsapi.cofeportal.org/v2/contacts?api_id={api_id}&data={data}&sig={sig}&end_date={end_date}&fields={fields}&limit={limit}&offset={offset}&start_date={start_date}
For more details, please see the section on request parameters.
The following search parameters can be used as part of the JSON data string:
| Name | Type | Notes |
|---|---|---|
| diocese_id | Integer | Required |
| keyword | String | This is an optional text string to match, e.g. ‘smith’ or ‘john smith’. The later would return contacts matching ‘john’ OR ‘smith’. You can use AND or NOT as well. e.g. ‘John AND Smith’ would find all contacts matching both John AND smith. |
| keyword_names_only | Only include this if you would like to restrict the keyword to only search against the forenames, surname and known_as fields. Use in conjunction with "keyword". Value of parameter should equal "on". | |
| places | Array | This is a list of place id’s to refine the results for. Submit the values as an array. |
| roles | Array | This contains a list of optional role id’s that you would like to return contacts for. Submit the values as an array. Role id’s can be found within the CMS and is a more accurate method of ensuring you are returning the correct matches. It is not affected if you change the role name. |
| date_period | String | This value sets the date period for which to return contacts with posts. Options are:
|
| postcode | String | This is an optional text string matching the postcode. It should be used in conjunction with postcode_radius to return all contacts within the provided radius of the postcode. |
| postcode_radius | String | This is a value in miles. Used in conjunction with the postcode parameter. |
| deceased | Include this if you would like to include deceased contacts within your response. Value of parameter should equal "on". | |
| sort_order | String | Options are:
|
A JSON object containing none or more CMS contacts or an error response. The fields return will either be the default set of fields available for the CMS API v2.4 or a limited set fields based on the field list supplied with the request.
If no fields are specified as part of the request, the following default fields will be return with the response:
| Name | Type | Notes |
|---|---|---|
| id | Integer | ID of the contact. |
| contactable | Boolean | This field is used to indicate whether you are allowed to contact this contact. |
| is_deceased | Boolean | This field is used to indicate whether the contact is deceased. |
| publish_web | Boolean | This field is used to indicate whether permission has been given for this contact to be published on public facing websites. Please note: you will still need to use permission setting for the display of individual fields related to this contact. This is labelled as "Include in national directory" within the CMS. |
| publish_directory | Boolean | This field is used to indicate whether permission has been given for this contact to be published in a directory. Please note: you will still need to use permission setting for the display of individual fields related to this contact. This is labelled as "Include in printed directory" within the CMS. |
| surname | String | |
| surname_privacy_setting | Integer | The privacy setting for the surname field. For more information on privacy settings please refer to the privacy settings section below. |
| previous_surname | String | |
| previous_surname_privacy_setting | Integer | The privacy setting for the previous surname field. For more information on privacy settings please refer to the privacy settings section below. |
| forenames | String | |
| forenames_privacy_setting | Integer | The privacy setting for the forenames field. For more information on privacy settings please refer to the privacy settings section below. |
| initials | String | |
| initials_privacy_setting | Integer | The privacy setting for the initial field. For more information on privacy settings please refer to the privacy settings section below. |
| known_as_forenames | String | |
| known_as_forenames_privacy_setting | Integer | The privacy setting for the known as forenames field. For more information on privacy settings please refer to the privacy settings section below. |
| known_as_surname | String | |
| known_as_surname_privacy_setting | Integer | The privacy setting for the known as surname field. For more information on privacy settings please refer to the privacy settings section below. |
| gender | String | |
| gender_privacy_setting | Integer | The privacy setting for the gender field. For more information on privacy settings please refer to the privacy settings section below. |
| title | String | |
| title_privacy_setting | Integer | The privacy setting for the title field. For more information on privacy settings please refer to the privacy settings section below. |
| address1_label | String | |
| address1_label_privacy_setting | Integer | The privacy setting for the address 1 label field. For more information on privacy settings please refer to the privacy settings section below. |
| address1_line1 | String | |
| address1_line1_privacy_setting | Integer | The privacy setting for the address 1 line 1 field. For more information on privacy settings please refer to the privacy settings section below. |
| address1_line2 | String | |
| address1_line2_privacy_setting | Integer | The privacy setting for the address 1 line 2 field. For more information on privacy settings please refer to the privacy settings section below. |
| address1_line3 | String | |
| address1_line3_privacy_setting | Integer | The privacy setting for the address 1 line 3 field. For more information on privacy settings please refer to the privacy settings section below. |
| address1_line4 | String | |
| address1_line4_privacy_setting | Integer | The privacy setting for the address 1 line 4 field. For more information on privacy settings please refer to the privacy settings section below. |
| address1_town | String | |
| address1_town_privacy_setting | Integer | The privacy setting for the address 1 town field. For more information on privacy settings please refer to the privacy settings section below. |
| address1_county | String | |
| address1_county_privacy_setting | Integer | The privacy setting for the address 1 county field. For more information on privacy settings please refer to the privacy settings section below. |
| address1_postcode | String | |
| address1_postcode_privacy_setting | Integer | The privacy setting for the address 1 postcode field. For more information on privacy settings please refer to the privacy settings section below. |
| address1_country | String | |
| address1_country_privacy_setting | Integer | The privacy setting for the address 1 country field. For more information on privacy settings please refer to the privacy settings section below. |
| address2_label | String | |
| address2_label_privacy_setting | Integer | The privacy setting for the address 2 label field. For more information on privacy settings please refer to the privacy settings section below. |
| address2_line1 | String | |
| address2_line1_privacy_setting | Integer | The privacy setting for the address 2 line 1 field. For more information on privacy settings please refer to the privacy settings section below. |
| address2_line2 | String | |
| address2_line2_privacy_setting | Integer | The privacy setting for the address 2 line 2 field. For more information on privacy settings please refer to the privacy settings section below. |
| address2_line3 | String | |
| address2_line3_privacy_setting | Integer | The privacy setting for the address 2 line 3 field. For more information on privacy settings please refer to the privacy settings section below. |
| address2_line4 | String | |
| address2_line4_privacy_setting | Integer | The privacy setting for the address 2 line 4 field. For more information on privacy settings please refer to the privacy settings section below. |
| address2_town | String | |
| address2_town_privacy_setting | Integer | The privacy setting for the address 2 town field. For more information on privacy settings please refer to the privacy settings section below. |
| address2_county | String | |
| address2_county_privacy_setting | Integer | The privacy setting for the address 2 county field. For more information on privacy settings please refer to the privacy settings section below. |
| address2_postcode | String | |
| address2_postcode_privacy_setting | Integer | The privacy setting for the address 2 postcode field. For more information on privacy settings please refer to the privacy settings section below. |
| address2_country | String | |
| address2_country_privacy_setting | Integer | The privacy setting for the address 2 country field. For more information on privacy settings please refer to the privacy settings section below. |
| home_phone | String | |
| home_phone_privacy_setting | Integer | The privacy setting for the home phone field. For more information on privacy settings please refer to the privacy settings section below. |
| work_phone | String | |
| work_phone_privacy_setting | Integer | The privacy setting for the work phone field. For more information on privacy settings please refer to the privacy settings section below. |
| mobile | String | |
| mobile_privacy_setting | Integer | The privacy setting for the mobile field. For more information on privacy settings please refer to the privacy settings section below. |
| fax | String | |
| fax_privacy_setting | Integer | The privacy setting for the fax field. For more information on privacy settings please refer to the privacy settings section below. |
| email_address | String | |
| email_address_privacy_setting | Integer | The privacy setting for the email address field. For more information on privacy settings please refer to the privacy settings section below. |
| email_address2 | String | |
| email_address2_privacy_setting | Integer | The privacy setting for the email address 2 field. For more information on privacy settings please refer to the privacy settings section below. |
| profile_photo | String | The full URL of the contact's current profile photo image, if one exists. |
| created_at | Timestamp | The date and time the record was created. |
| updated_at | Timestamp | The date and time the record was last updated. |
| purged_at | Timestamp | The date and time the record was purged. |
| deleted_at | Timestamp | The date and time the record was deleted. |
| informal_name | String |
WarningThe informal name field has been DEPRECATED as of Version 2.3 and will be REMOVED in a future version of the CMS API. Please use the |
| informal_name_privacy_setting | Integer |
WarningThe informal name privacy setting field has been DEPRECATED as of Version 2.3 and will be REMOVED in a future version of the CMS API. Please use the |
The privacy settings fields are returned as integer values, which translate as follows:
| Value | Name | Description |
|---|---|---|
| 0 | Public | Available for public domain. |
| 1 | Diocese | CMS users, within the contact's Diocese, only. |
| 2 | Private | Authorised access only. |