You can use the following API methods to Get a Person, Find a Person, Add a Person, Update a Person, and Add/Update a Person by external_person_id.
Get a Person
The following will retrieve a Person by its person_key, or external_person_id. Person_id can also be used, however this field is deprecated and may not be present in future API versions.
You must provide a valid person_key or external_person_id.
| Code Block |
|---|
GET /companies/:company_key/mobiledb/persons/:person_key
GET /companies/:company_key/mobiledb/persons/external/:external_person_id
GET /companies/:company_key/mobiledb/persons/:person_id |
| Note |
|---|
| Note: A 404 - Not Found error will be returned if the Person cannot be located. |
Request JSON
There is no Request JSON with a GET.
Return JSON
A Person entity.
| Note |
|---|
| Note: The following example is of Version 2 of the APIs that uses the E.164 international MDN format. If you are using Version 1 of the API, you cannot use the E.164 format. |
| Code Block |
|---|
{
"person_id": "987654",
"custom_fields": {
"Home_Zip": "12345",
"push_test_home_ownership": null,
"device_type": null,
"push_test_first_name": null,
"company_timezone": "US/Central",
"push_test_sports_select": [],
"passid": "wd1377r4",
"department": null,
"first_name": "Bob",
"locations": [],
"company_native_push_enabled": null,
"birthdate": "1990-12-01T00:00:00z",
"company_location": [],
"push_test_birthdate": "1990-12-01T00:00:00z",
"loyalty_id": "111234567",
"fashion_preference": "business",
"email": "bob@company.com",
"last_name": "Smith",
"Work_Zip": "12345",
"gender": {
"id": null,
"name": "Male",
"option_key": "male",
"active": true
},
"statecounty": null,
"recipient_list": null
},
"external_person_id": "542342",
"timezone": "US/Central",
"timezone_source": "api",
"mobile_phone": {
"mdn": "+12995551234",
"carrier_code": "104"
},
"created_at": "2013-06-11T20:54:08Z",
"updated_at": "2017-04-24T14:33:21Z",
"url": "/companies/:company_key/mobiledb/persons/wd1377r4"
} |
- An HTTP 201 status code means the created response will be returned if the object has been successfully created.
- An HTTP 200 status code means that an OK result will be returned if an existing Person record already exists with the same mobile_phone. The record will be updated with the added information. Specified fields in the add request will be applied and any existing data fields on the record will remain unchanged.
- An HTTP 200 status code can also mean that an OK result will be returned if an external_person_id value is specified that already exists, and will attempt to update the existing Person record with the supplied data fields.
- An HTTP 422 Unprocessable Entity response status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
Find a Person
The following will locate Person record(s) by other search criteria. Valid search fields can be: mdn.
| Code Block |
|---|
GET /companies/:company_key/mobiledb/persons?mdn=:mdn
|
A maximum of 25 records will be returned for locating a Person.
| Note |
|---|
| Note: A 404 - Not Found error will be returned if you do not specify an Mobile Directory Number (MDN) parameter for this index route, if the MDN is in an incorrect format, or if a Person cannot be found. |
Request JSON
There is no Request JSON with a GET.
Return JSON
An array of Person elements will be returned for the first 25 Person objects that matched the search query.
| Note |
|---|
| Note: The following example is of Version 2 of the APIs that uses the E.164 international MDN format. If you are using Version 1 of the API, you cannot use the E.164 format. |
| Code Block |
|---|
[
{
"person_id": "987654",
"external_person_id": "542342",
"mobile_phone": {
"mdn": "+12995551234",
"carrier_code": "104"
},
"custom_fields": {
"first_name": "Steve",
"rewards_id": "543557654",
"favorite_stores": [
{
"id": "4",
"name": "My Hardware Store",
"option_key": "my_hardware_store"
},
{
"id": "12",
"name": "Local Grocery",
"option_key": "local_grocery"
}
]
},
"timezone": "US/Central",
"timezone_source": "api",
"created_at": "2017-01-05T14:30Z",
"updated_at": "2017-02-08T19:30Z"
},
{
"person_key": "w2e2127r-w413-841w-8t40-480b85dc6t3e",
"external_person_id": "54234234",
"mobile_phone": {
"mdn": "+12995554321",
"carrier_code": "102"
},
"custom_fields": {
"first_name": "Bob",
"birthdate": "1990-12-01T00:00:00Z",
"rewards_id": "543557654",
"favorite_stores": [
{
"id": "12",
"name": "Local Grocery",
"option_key": "local_grocery"
}
]
},
"timezone": "US/Central",
"timezone_source": "api",
"created_at": "2017-01-05T14:30Z",
"updated_at": "2017-02-08T19:30Z",
"url": "/companies/:company_key/mobiledb/persons/wd1377r4"
}
]
|
Add a Person
Use the following to create a new Person record.
| Code Block |
|---|
POST /companies/:company_key/mobiledb/persons/
|
Request JSON
| Code Block |
|---|
{
"external_person_id": "542342",
"mobile_phone": {
"mdn": "2995551234"
},
"custom_fields": {
"first_name": "Steve",
"rewards_id": "543557654",
"favorite_stores": [
{
"option_key": "my_hardware_store"
},
{
"option_key": "local_grocery"
}
]
}
} |
The person_id, timezone_source, created_at and updated_at fields are not allowed, and any values will be ignored.
One of mobile_phone or external_person_id must be supplied. All custom fields are also optional and may be omitted.
Return JSON
A Person entity.
| Code Block |
|---|
{
"person_id": "987654",
"external_person_id": "542342",
"mobile_phone": {
"mdn": "+12995551234",
"carrier_code": "104"
},
"custom_fields": {
"first_name": "Steve",
"rewards_id": "543557654",
"favorite_stores": [
{
"id": "4",
"name": "My Hardware Store",
"option_key": "my_hardware_store"
},
{
"id": "12",
"name": "Local Grocery",
"option_key": "local_grocery"
}
]
},
"timezone": "US/Central",
"timezone_source": "api",
"created_at": "2017-01-05T14:30Z",
"updated_at": "2017-02-08T19:30Z",
"url": "/companies/:company_key/mobiledb/persons/wd1377r4"
} |
- An HTTP 201 status code means the created response will be returned if the object has been successfully created.
- An HTTP 200 status code means that an OK result will be returned if an existing Person record already exists with the same mobile_phone. The record will be updated with the added information. Specified fields in the add request will be applied and any existing data fields on the record will remain unchanged.
- An HTTP 200 status code means that an OK result will be returned if an existing Person record already exists, either with the external_person_id or with the same mobile_phone. The record will be updated with the added information. Specified fields in the PUT request will be applied, and any existing data fields on the record will remain unchanged. The external_person_id of the Person in the URL will change to the external_person_id in the request if specified.
- An HTTP 409 - Conflict Error will be returned if the update contains a mobile_phone value that already exists.
| Anchor |
|---|
UpdatePerson | UpdatePerson | Update PersonThe following will perform a Net - An HTTP 422 Unprocessable Entity response status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
Update PersonThe following will perform a Net Change update to an existing Person record.
| Code Block |
|---|
PUT /companies/:company_key/mobiledb/persons/:person_key |
Request JSON
| Code Block |
|---|
{
"custom_fields": {
"first_name": "Bob",
"favorite_stores": [
{
"option_key": "new_store"
}
],
"points":100
}
} |
| Note |
|---|
Notes: - An HTTP 200 status code means that an OK result will be returned if the operation completes successfully.
- An HTTP 404 - Not Found error will be returned if the entity does not exist.
|
The person_key, timezone_source, created_at and updated_at fields are not allowed in the body of the update, and any values will be ignored.
The mobile_phone value can be removed by specifying null, but it cannot be changed to a new phone number. If an MDN is specified with a changed, non-null value, an HTTP 409 - Conflict Error will be returned.
Any fields that are specified will be updated with the new values. Any fields whose value is set to null will be removed from the Person. Any fields completely omitted will be ignored and any existing values will remain.
Return JSON
| Note |
|---|
| Note: The following example is of Version 2 of the APIs that uses the E.164 international MDN format. If you are using Version 1 of the API, you cannot use the E.164 format. |
A Person entity reflecting the new state of the Person.
| Code Block |
|---|
{
"person_id": "987654",
"external_person_id": "542342",
"mobile_phone": {
"mdn": "+12995551234",
"carrier_code": "104"
},
"custom_fields": {
"first_name": "Bob",
"rewards_id": "543557654",
"favorite_stores": [
{
"id": "4",
"name": "My Hardware Store",
"option_key": "my_hardware_store"
},
{
"id": "12",
"name": "Local Grocery",
"option_key": "local_grocery"
},
{
"id": "8",
"name": "Brand New Store",
"option_key": "new_store"
}
],
"points":100
},
"timezone": "US/Central",
"timezone_source": "api",
"created_at": "2017-01-05T14:30Z",
"updated_at": "2017-02-08T19:30Z",
"url": "/companies/:company_key/mobiledb/persons/wd1377r4"
} |
- An HTTP 201 status code means the created response will be returned if the object has been successfully created.
- An HTTP 200 status code means that an OK result will be returned if an existing Person record already exists with the same mobile_phone. The record will be updated with the added information. Specified fields in the add request will be applied and any existing data fields on the record will remain unchanged.
- An HTTP 200 status code means that an OK result will be returned if an existing Person record already exists, either with the external_person_id or with the same mobile_phone. The record will be updated with the added information. Specified fields in the PUT request will be applied, and any existing data fields on the record will remain unchanged. The external_person_id of the Person in the URL will change to the external_person_id in the request if specified.
- An HTTP 409 - Conflict Error will be returned if an update to the Person's existing mobile_phone is attempted.
- An HTTP 422 Unprocessable Entity response status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
| Anchor |
|---|
| addupdateaperson |
|---|
| addupdateaperson |
|---|
|
Add/Update a Person (by external_person_id)
The following will create and/or update a Person record that is identified by the external_person_id.
| Code Block |
|---|
PUT /companies/:company_key/mobiledb/persons/external/:external_person_id
|
Request JSON
| Code Block |
|---|
{
"external_person_id": "542342",
"mobile_phone": {
"mdn": "2995551234"
},
"custom_fields": {
"first_name": "Steve",
"rewards_id": "543557654",
"favorite_stores": [
{
"option_key": "my_hardware_store"
},
{
"option_key": "local_grocery"
}
]
}
} |
The person_id, timezone_source, created_at and updated_at fields are not allowed in a PUT request, and any values will be ignored.
The mobile_phone field is optional and can be omitted. All custom fields are also optional and may be omitted.
Return JSON
A Person entity.
| Code Block |
|---|
{
"person_id": "987654",
"external_person_id": "542342",
"mobile_phone": {
"mdn": "+12995551234",
"carrier_code": "104"
},
"custom_fields": {
"first_name": "Bob",
"rewards_id": "543557654",
"favorite_stores": [
{
"id": "4",
"name": "My Hardware Store",
"option_key": "my_hardware_store"
},
{
"id": "12",
"name": "Local Grocery",
"option_key": "local_grocery"
},
{
"id": "8",
"name": "Brand New Store",
"option_key": "new_store"
}
],
"points":100
},
"timezone": "US/Central",
"timezone_source": "api",
"created_at": "2017-01-05T14:30Z",
"updated_at": "2017-02-08T19:30Z",
"url": "/companies/:company_key/mobiledb/persons/wd1377r4"
} |
- An HTTP 201 status code means the created response will be returned if the object has been successfully created.
- An HTTP 200 status code means that an OK result will be returned if an existing Person record already exists, either with the external_person_id or with the same mobile_phone. The record will be updated with the added information. Specified fields in the PUT request will be applied, and any existing data fields on the record will remain unchanged. The external_person_id of the Person in the URL will change to the external_person_id in the request if specified.
- An HTTP 409 - Conflict Error will be returned if an update to the Person's existing mobile_phone is attempted.
- An HTTP 422 Unprocessable Entity response status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.