Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Last Updated:

Lastupdatedate

Livesearch
placeholderSearch the Vibes Developer Wiki
typepage




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.

Anchor
getaperson
getaperson
Get a Person

The following will retrieve a Person by its person_id, person_key, or external_person_id. You must provide a valid person_id. The key or external_person_id is a sequential integer assigned by the database when the record is created in the database.

Code Block
GET /companies/:company_idkey/mobiledb/persons/:person_idkey
GET /companies/:company_id/mobiledb/persons/:person_key
GET /companies/:company_id/mobiledb/persons/external/:external_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": "wd1377r4",
  "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_idkey/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.

Anchor
findaperson
findaperson
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_idkey/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_idkey": "AB342321w2e27r-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_idkey": "AB34223413w2e2127r-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"
  }
]

Anchor
AddPerson
AddPerson
Add a Person

Use the following to create a new Person record.

Code Block
POST /companies/:company_idkey/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.

Anchor
UpdatePerson
UpdatePerson
Update Person

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

Code Block
PUT /companies/:company_idkey/mobiledb/persons/:person_idkey 


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_idkey, 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
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_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_idkey/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.

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_idkey/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.