Platform Developer Documentation
Skip to end of metadata
Go to start of metadata

Last Updated: Wednesday, August 3, 2022

Available API methods



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. 

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: 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_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.

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

POST /companies/:company_key/mobiledb/persons/

Request JSON

{
    "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.

{
    "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.
  • 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 Person

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

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

Request JSON

{
"custom_fields": {
    "first_name": "Bob",
    "favorite_stores": [
        {
          "option_key": "new_store"
        }
	],
	"points":100
	}
}


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

{
    "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.

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

Request JSON

{
    "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.

{
    "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.


  • No labels

6 Comments

  1. Steven Mastandrea

    We need to work TenantKey into the URL as well, or take the company and infer it. 

    ANSWER: We are going to take the company in the URL

  2. Steven Mastandrea

    Evan: Should add/update just return full entity data?

    1. Unknown User (matt.campbell)

      I think add/update should return the full entity data. This makes the response body consistent and eliminates the need to do a GET to see the whole picture. Shall I go ahead and change the spec?

    2. Steven Mastandrea

      We should return the full entity data because we support/encourage net change updates.

  3. Unknown User (matt.campbell)

    I would like to propose we consider not allowing clients to specify carriers, and instead let mobiledb look them up all the time. It would prevent out clients loading bad carriers in, which would cause their patrons to lose their mobile_phones and subscriptions the first time they send us an MO. It would also prevent problems where they specify a wrong carrier for and existing mobile_phone in mobiledb, which we then return as an error because we don't allow carrier changes through the persons API.

    Thoughts?

  4. Sam Benediktson

    Change an MDN

    FOR THE FUTURE

    PUT /companies/:company_id/mobiledb/persons/:person_id/mdns/:mdn
PUT /companies/:company_id/mobiledb/persons/external/:external_person_id/mdns/:mdn

    This will change the MDN that is associated with the existing person record, and prompt the user for confirmation on the new MDN. Upon confirmation, all of the subscriptions for the person will be moved to the new MDN. If a different person record already exists with the MDN, the records will be merged upon confirmation?

    An HTTP 404 - Not Found will be returned if the Person does not exist or is not

    Request JSON

    {
   "mdn":"8475551213"
}

    The mdn field is the new MDN to change to. The existing MDN is in the URL path of the request.

    Return JSON

    No body is returned and an HTTP 204 - No Content will be returned if the update was successful.