Skip to main content

Voyado Engage

Create a new contact

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

https://[client].voyado.com/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)

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

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.

Payload to create a new contact

You should specify the contactType in the payload. However, if contactType is not specified, it will default to Member like in the following (minimal but functional) payload example:

{
  "firstName": "Example",
  "email": "example@example.com",
  "countryCode": "SE"
}

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.

Caution

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

Contact created

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

{
  "id": "e8f17b1d-b680-4688-862b-af38009a726e",
  "attributes": {
    "firstName": "Example",
    "lastName": null,
    "street": null,
    "zipCode": null,
    "city": null,
    "email": "example@example.com",
    "mobilePhone": null,
    "countryCode": "SE",
    "careOf": null,
    "country": null,
    "age": null,
    "birthDay": null,
    "externalId": null,
    "socialSecurityNumber": null,
    "gender": null,
    "staff": false,
    "memberNumber": "999032095",
    ...
    "currentStore": {
      "id": "b5e553d1-e4ba-40a0-8ee4-a9f631ee950b",
      "name": "Supershop E-commerce SE, 911",
      "externalId": "911"
    }
  },
  "meta": {
    "createdOn": "2022-10-24T11:22:19+02:00",
    "modifiedOn": "2022-10-24T11:22:19+02:00",
    "sourceType": "API",
    "approved": true,
    "contactType": "Member"
  },
  "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.

Response codes

A successful creation will return this response, along with the data set:

'201' : Created

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

'400' : NoData

'409' : ApprovedContactWithKeyExists, ContactWithKeyIsBeingCreatedContactNotFound

'422' : ValidationError