Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 100 Next »

Last Updated: Tuesday, October 29, 2019




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. You must provide a valid person_key or external_person_id.

GET /companies/:company_key/mobiledb/persons/:person_key
GET /companies/:company_key/mobiledb/persons/external/:external_person_id
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: 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.
{
  "person_key": "21w2e27r-w413-841w-8t40-45dc6t3e80b8",
  "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.

Find a Person

The following will locate Person record(s) by other search criteria. Valid search fields can be: mdn.

GET /companies/:company_key/mobiledb/persons?mdn=:mdn

A maximum of 25 records will be returned for locating a Person.

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: 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.
[
  {
    "person_key": "21w2e27r-w413-841w-8t40-45dc6t3e80b8",
    "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"
  }
]

Add a Person

Use the following to create a new Person record.

POST /companies/:company_key/mobiledb/persons/

The person_id, timezone_sourcecreated_at and updated_at fields are not allowed, 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.

  • 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.

Update Person

The following will perform a Net Change update to an existing Person record.

PUT /companies/:company_key/mobiledb/persons/:person_key 


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_sourcecreated_at and updated_at fields are not allowed in the body of the update, and any values will be ignored.

The MDN field cannot be changed. If the value is specified and has changed, 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

A Person entity reflecting the new state of the Person.

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.
{
  "person_key": "21w2e27r-w413-841w-8t40-45dc6t3e80b8",
  "custom_fields": {
    "Home_Zip": "01234",
    "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": "111234566",
    "fashion_preference": "business",
    "email": "bob@company2.com",
    "last_name": "Smith_Johnson",
    "Work_Zip": "01234",
    "gender": {
      "id": null,
      "name": "Male",
      "option_key": "male",
      "active": true
    },
    "statecounty": null,
    "recipient_list": null
  },
  "external_person_id": "542342",
  "timezone": "US/Central",
  "mobile_phone": {
    "mdn": "+12995551234",
    "carrier_code": "104"
  },
  "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.

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.

PUT /companies/:company_key/mobiledb/persons/external/:external_person_id

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.

  • 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.


  • No labels