Retrieves a single records containing post, place, contact and role fields from the CMS API v2.4 based on the supplied parameters.
| Method | URL |
|---|---|
GET |
/v2/posts/{id} |
Where {id} is the ID of the post record you wish to retrieve.
| Response format | JSON |
| Paginated? | No |
| 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 |
| 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: {
"post" : [
"start_date",
"end_date",
"comments"
],
"contact" : [
"forenames",
"surname",
"known_as_forenames"
],
"role" : [
"role_name"
],
"place" : [
"name"
]
}
To retrieve a list of available fields the CMS API v2.4 supports, please refer to the following API endpoints: |
https://cmsapi.cofeportal.org/v2/posts/{id}?api_id={api_id}&data={data}&sig={sig}&fields={fields}
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 |
A JSON object containing a CMS post or an error response. Each post return will have it's data grouped by type. For example a response might contain post fields, contact field, role fields and place fields. 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 post. |
| proxy_post_id | Integer | ID of the post that is proxying this post. |
| contact_id | Integer | ID of the contact. |
| diocese_role_id | Integer | ID of the role. |
| place_id | Integer | ID of the place. |
| start_date | date | The date the post started. |
| end_date | date | The date the post ended. |
| post_name | String | Custom post name given by Diocese. |
| percentage_fulltime | float | |
| is_primary | Boolean | Is this the contacts primary post? |
| comments | Text | |
| created_at | Timestamp | The date and time the record was created. |
| updated_at | Timestamp | The date and time the record was last updated. |
| deleted_at | Timestamp | The date and time the record was deleted. |
Each post can be optionally assigned a post type. The returned data will also include the following post type fields.
| Name | Type | Notes |
|---|---|---|
| id | Integer | ID of the post type. |
| name | String | Name of the post type. |
| 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. |
| Name | Type | Notes |
|---|---|---|
| id | Integer | ID of the post. |
| role_name | String | |
| is_public_job_role | Boolean | Whether or not this role can be displayed in the public domain. |
| sort | Integer |
| Name | Type | Notes |
|---|---|---|
| id | Integer | ID of the place. |
| parent_id | Integer | ID of the parent place. |
| place_type_id | Integer | The ID of the place type. |
| building_id | Integer | The ID of the building, if building data has been associated to this place. |
| name | String | |
| alternative_name | String | |
| national_reference | String | |
| diocesan_reference | String | |
| other_reference | String | |
| charity_commission_reference | String | |
| website | String | |
| comments | Text | |
| plurality | String | |
| patron | String | |
| population | String | |
| electoral_roll | String | |
| created_at | Timestamp | The date and time the record was created. |
| updated_at | Timestamp | The date and time the record was last updated. |
| deleted_at | Timestamp | The date and time the record was deleted. |
| redundant_at | Timestamp | The date and time the record was made redundant. |
Places can optionally have building data associated to them, so in addition to the place fields, the returned data shall also include the following building fields.
| Name | Type | Notes |
|---|---|---|
| longitude | String | |
| latitude | String | |
| chr_asset_id | String | The ID for the place on the third party website Church Heritage Record. |
| address_line1 | String | |
| address_line2 | String | |
| address_line3 | String | |
| town | String | |
| county | String | |
| postcode | String | |
| country | String | |
| phone | String | |
| fax | String | |
| email_address | String | |
| notes | String | |
| profile_photo | String | |
| alternative_phone | String | |
| church_listing | String | |
| opening_times | String | |
| conservation_area | String | |
| quinquennial_inspections | String | |
| braile | String | |
| choir | String | |
| music | String | |
| church_type | String | |
| acny_id | String | The ID for the place on the third party website A Church Near You. |
| accomodation | String | |
| year_built | String | |
| local_authority | String | |
| deanery_synod_number | String | |
| bishop_permission | String | |
| bishop_permission_date | String | |
| lep | String | |
| usaa | String | |
| disabled_access | String | |
| hearing_loop | String | |
| large_print_resources | String | |
| parking | String | |
| wc | String | |
| fair_trade | String | |
| youth_work | String | |
| sunday_school | String | |
| creche | String | |
| baby_change_facilities | String | |
| church_hall | String | |
| churchyard | String | |
| bells | String | |
| disabled_partial | String | |
| disabled_wc | String | |
| projector | String | |
| siams_report | String | |
| local_education_authority | String | |
| area | String | |
| school_status | String | |
| range | String | |
| dfe_number | String | |
| ofsted_urn | String | |
| national_society_reference | String | |
| children_on_roll | String | |
| num_governors | String | |
| num_foundation_governors | String |
Each place has been assigned a specific place type. In addition to the place_type_id included as part of the place fields, the returned data will also include the following place type fields. A list of possible place types can be found above.
| Name | Type | Notes |
|---|---|---|
| name | String |
[
{
"post": {
"id": XXXXX,
"proxy_post_id": 0,
"contact_id": XXXXXX,
"diocese_role_id": XXXX,
"place_id": XXXXX,
"start_date": null,
"end_date": null,
"percentage_fulltime": 0,
"is_primary": 1,
"comments": "",
"created_at": "2016-02-05 13:04:39",
"updated_at": "2016-03-31 13:31:21",
"deleted_at": null
},
"role": {
"id": XXXX,
"role_name": "Church Warden"
},
"contact": {
"id": XXXXXX,
"contactable": 1,
"is_deceased": 0,
"surname": "Smith",
"surname_privacy_setting": 0,
"forenames": "John",
"forenames_privacy_setting": 0,
"initials": "J",
"initials_privacy_setting": 0,
"known_as_forenames": "John",
"known_as_forenames_privacy_setting": 1,
"gender": "Male",
"gender_privacy_setting": 1,
"title": "Mr",
"title_privacy_setting": 0,
"address1_label": "Work Address",
"address1_label_privacy_setting": 1,
"address1_line1": "The House",
"address1_line1_privacy_setting": 1,
"address1_line2": "Street name",
"address1_line2_privacy_setting": 1,
"address1_line3": "Town",
"address1_line3_privacy_setting": 1,
"address1_town": "City",
"address1_town_privacy_setting": 1,
"address1_county": "",
"address1_county_privacy_setting": 1,
"address1_postcode": "XX1 1XX",
"address1_postcode_privacy_setting": 1,
"address1_country": "0",
"address1_country_privacy_setting": 0,
"address2_label": "",
"address2_label_privacy_setting": 1,
"address2_line1": "",
"address2_line1_privacy_setting": 1,
"address2_line2": "",
"address2_line2_privacy_setting": 1,
"address2_line3": "",
"address2_line3_privacy_setting": 1,
"address2_town": "",
"address2_town_privacy_setting": 1,
"address2_county": "",
"address2_county_privacy_setting": 1,
"address2_postcode": "",
"address2_postcode_privacy_setting": 1,
"address2_country": "0",
"address2_country_privacy_setting": 0,
"home_phone": "",
"home_phone_privacy_setting": 1,
"work_phone": "(01234) 567890",
"work_phone_privacy_setting": 1,
"mobile": "",
"mobile_privacy_setting": 1,
"fax": "",
"fax_privacy_setting": 1,
"email_address": "[email protected]",
"email_address_privacy_setting": 1,
"email_address2": "",
"email_address2_privacy_setting": 1,
"created_at": "2016-02-05 13:03:40",
"updated_at": "2016-02-05 13:03:40",
"deleted_at": null,
"informal_name": "John",
"informal_name_privacy_setting": 1
},
"place": {
"id": XXXXX,
"parent_id": XXXXX,
"place_type_id": 1,
"name": "Diocese of X",
"alternative_name": "",
"national_reference": "",
"diocesan_reference": "",
"other_reference": "",
"charity_commission_reference": "",
"website": null,
"comments": "",
"plurality": "",
"patron": "",
"population": null,
"electoral_roll": null,
"created_at": "2016-02-05 13:02:44",
"updated_at": "2016-02-05 13:02:44",
"deleted_at": null,
"redundant_at": null,
"address_line1": null,
"address_line2": null,
"address_line3": null,
"town": null,
"county": null,
"postcode": null,
"country": null,
"longitude": null,
"latitude": null,
"phone": null,
"fax": null,
"email_address": null,
"acny_id": null,
"notes": null,
"place_type_name": "Diocese"
}
}
]