Skip to main content

Create contact

A vital part of any Voyado Engage integration journey is registering new contacts. This is done via the following endpoint:

POST /api/v2/contacts

This endpoint can be used to create a contact with contactType of Contact, Member or any of your custom types. You will need to provide the mandatory fields for your specific contact type along with the key value, which is one of the following:

  • mobilePhone

  • email

  • externalId

  • socialSecurityNumber (Swedish/Finnish)

Caution

Before you try to create them, always check if the contact already exists. For this, use the ID-lookup service (explained here) where multiple identifiers can be tested to confirm if they exist in the database or not.

Headers

There are three optional parameters that can be sent in the request header.

Parameter

Type

Description

source

string

This shows how the contact was created. Example values here are "POS" or "e-com".

storeExternalId

string

The unique id of the store or market the customer signed up in (the recruited-by store). Often this is a numerical code, like "600".

createAsUnapproved

string

This creates an unverified contact which then must be verified by some other process or action, such as clicking a link in an email. It can be "true" or "false". An unverified contact like this will be ignored in reports and won't be included in segmentations until specifically asked for. The default value is "false" so if you are not using this, you don't need to worry about it.

Caution

While not mandatory, It is highly recommended to send both source and storeExternalId in the header as it reduces problems later on.

Caution

While it is possible to send in any source value you like in the header, to be able to segment/isolate them in Engage the source also needs to be added in the back-end by your Voyado team. Contact them to do this.

Payload to create a new contact

You should specify the contactType in the payload. This needs to be a contactType that already exists. If you give one that doesn't exist, you will get an error and the new contact will not be created.

If contactType is not specified in your payload at all, it will default to Member.

{
  "firstName": "Example",
  "email": "example@example.com",
  "countryCode": "SE",
  "birthDay": "1966-06-26",
  "lang":"en",
  "contactType": "ExampleContactType",
  "preferences": {
    "acceptsEmail": true,
    "acceptsPostal": true,
    "acceptsSms": true
  },
  "consents": [{
      "id": "memberConsent",
      "value": true,
      "date": "2022-01-01T00:00:00+0100",
      "source": "ECOM",
      "comment": "Approved member terms at checkout"
   }]
}

The value of countryCode is mostly used in segmentation, to decide which language to use when communicating with an end-user. It is based primarily on their address data or else on the store where they have signed up (which might not be where they live).

So, in terms of understanding and communicating with the end-user, it is important that countryCode is correct. Your POS should have the option to easily update the end-user's countryCode when it's necessary. For countries using multiple languages the lang attribute is used.

Caution

The field countryCode is not mandatory when creating a contact but it is highly recommended.

Caution

The field birthDay, if used, must have the format YYYY-MM-DD as in the example payload above. If it is used then age is calculated automatically when the contact is created.

Contact created

After the POST operation, this new contact is created and their complete data set is returned.

{
  "id": "e8f17b1d-b777-4688-862b-cf38009a726e",
  "attributes": {
    "firstName": "Example",
    "lastName": null,
    "street": null,
    "zipCode": null,
    "city": null,
    "email": "example@example.com",
    "mobilePhone": null,
    "countryCode": "SE",
    "careOf": null,
    "country": null,
    "age": 57,
    "birthDay": "1966-06-26",
    "externalId": null,
    "socialSecurityNumber": null,
    "gender": null,
    "staff": false,
    "memberNumber": "999032095",
    ...
    "currentStore": {
      "id": "b5e553d1-e4ba-40a0-8ee4-a9f631ee950b",
      "name": "Megashop E-commerce SE, 444",
      "externalId": "444"
    }
  },
  "meta": {
    "createdOn": "2022-10-24T11:22:19+02:00",
    "modifiedOn": "2022-10-24T11:22:19+02:00",
    "sourceType": "API",
    "approved": true,
    "contactType": "ExampleContactType"
  },
  "preferences": {
    "acceptsEmail": true,
    "acceptsPostal": true,
    "acceptsSms": true
  },
  "consents": [{
      "id": "memberConsent",
      "value": true,
      "date": "2022-01-01T00:00:00+0100",
      "source": "POS",
      "comment": "Approved member terms at checkout"
   }]
}

Note

For consents, only the fields id and value are mandatory.

Responses

A successful creation will return HTTP 201 Created along with the contact's data set as the response body.

If the request has not been successful, you'll get one of the following HTTP error codes:

  • 400 : NoData

  • 409: ApprovedContactWithKeyExists, ContactWithKeyIsBeingCreated

  • 422: InvalidEmailAddress, InvalidPhonenumber, InvalidSsn, Invalidstore, ValueRequired

Caution

Do not send null or empty values in the JSON payload when updating or creating a contact. Empty values will override existing values. Send only what you want to change.