Get enriched profile

Getting a contact’s full information is core to Engage’s power. It allows personalization, giving access to Engage’s full customer profiling in a single request. This service has many use cases:

Populating an e-com My Pages or other landing page with customer information
Allowing a POS system to display the complete customer profile
Enabling the staff member to act on an incorrect email address
Informing the customer about reward vouchers or individual offers soon to expire
Allowing the e-com to switch content panels depending on customer’s target audience

This is all achieved through the /contactoverview endpoint. The data from this endpoint might contain cached contact information. For real-time updates on contacts and their corresponding data (promotions, reward points, etc.) then go directly to each entity endpoint, such as for example /contacts/[contactId]/promotions.

The /contactoverview endpoint is not to be used as a contact lookup endpoint nor for ID-fetching. For this, use the other methods described here.

Parameters sent in a query string must always be URL encoded.

Using /contactoverview with contactId

If you know the contactId, you can fetch a contact’s data directly without using any other information. This is because contactId is guaranteed to always be unique for a contact, whereas this is not enforced for the the other personal identifiers.

GET /api/v3/contactoverview?contactId={contactId}

You can also send contactType if you want, as shown here, but it’s not mandatory in this case.

GET /api/v3/contactoverview?contactType={contactType}&contactId={contactId}

Using /contactoverview with email

With the email parameter, the contactType must also be sent.

GET /api/v3/contactoverview?contactType=member&email=jane.doe%40gmail.com

Using /contactoverview with mobilePhone

With the mobilePhone parameter, the contactType must also be sent.

GET /api/v3/contactoverview?contactType=member&mobilePhone=%2B46702291216

Using /contactoverview with socialSecurityNumber

This is the Swedish personal identity number, Finnish personal identity code or Swedish samordningsnummer (coordination number).

GET /api/v3/contactoverview?contactType=member&socialSecurityNumber=198506059738

With the socialSecurityNumber parameter, the contactType must also be sent.

Using /contactoverview with customKey

As the customKey value you can send either a contact’s memberNumber or externalId, depending on how your tenant is set up. Your Voyado Engage team can help you here.

GET /api/v3/contactoverview?contactType=member&customKey=999888777

With the customKey parameter, the contactType must also be sent.

Using /contactoverview with any

The “any” parameter will accept any of the above values. They are scanned in the following order:

email
socialSecurityNumber
mobilePhone
customKey

For example:

GET /api/v3/contactoverview?contactType=ecom&any=jane.doe%40gmail.com

Or:

GET /api/v3/contactoverview?contactType=contact&any=999888777

With the any parameter, the contactType must also be sent. Whenever you call /contactoverview with the contactId, sending contactType is optional. In all other cases, sending the contactType is mandatory.

Response

If the request has been successful, you’ll get a HTTP 200 OK response along with the contact’s data. Otherwise you’ll get one of the following HTTP error codes:

400: InvalidEmailAddress, InvalidPhoneNumber, InvalidSocialSecurityNumber, InvalidContactType, InvalidSearchQuery
404: ContactNotFound
409: MultipleMatches
500: InvalidSystemConfiguration

See example of response payload

{
  "id": "33ee9958-0e09-484f-b4c4-aa3e00e1e24c",
  "attributes": {
    "firstName": "Example",
    "lastName": "Examplesson",
    "street": "Examplegatan 12",
    "zipCode": "123 45",
    "city": "Examplestad",
    "email": "example@example.com",
    "mobilePhone": "+46739111111",
    "countryCode": "SE",
    "socialSecurityNumber": "198101010101",
    "gender": "Female",
    "careOf": null,
    "country": "Sverige",
    "birthDay": "1981-01-01",
    "externalId": null,
    "memberNumber": "999888777",
    "rfm": 46,
    "children": [
      "2007-11-28T00:00:00+01:00"
    ],
    "age": 35,
    "registrationDate": "2019-02-05T13:21:02+01:00",
    "secrecyMarked": false,
    "currentStore": {
      "id": "0b7037b4-b7f5-4c9d-97e6-aa3b00ccc140",
      "name": "Rotterdam",
      "externalId": "SE014"
    }
  },
  "meta": {
    "createdOn": "2019-04-29T15:42:25+02:00",
    "modifiedOn": "2020-05-31T04:02:27+02:00",
    "sourceType": "Import",
    "approved": true,
    "contactType": "Member",
    "recruitedByStore": {
      "id": "a9573a5a-c9bb-4593-abee-aa3b00ccc141",
      "name": "Nice",
      "externalId": "SE019"
    }
  },
  "preferences": {
    "acceptsEmail": true,
    "acceptsPostal": true,
    "acceptsSms": true
  },
  "tiers": {
    "expires": null,
    "tierName": "Bas",
    "remainingToUpgrade": 233,
    "basedOnPoints": 767,
    "tierId": "bas"
  },
  "consents": [
    {
      "id": "consentIntelligentOffers",
      "value": true,
      "date": "2019-05-06T14:00:51+02:00",
      "comment": "",
      "source": "ContactForm"
    },
    {
      "id": "consentSegmentation",
      "value": true,
      "date": "2019-05-06T14:00:51+02:00",
      "comment": "",
      "source": "ContactForm"
    },
    {
      "id": "consentGeneralTerms",
      "value": true,
      "date": "2019-05-06T14:00:51+02:00",
      "comment": "",
      "source": "ContactForm"
    }
  ],
  "audiences": [
    "Best Customers rolling 24 months",
    "My VIP Group",
    "Intergamma VIP",
    "Superbokare"
  ],
  "warnings": [
    "MissingMobileNumber"
  ],
  "rewardVouchers": [
    {
      "expiresOn": "2020-08-31T23:59:59+02:00",
      "id": "880adf9c-b70b-47a8-b746-aaf900528332",
      "voucherNumber": "0000000000161",
      "name": "Generate reward vouchers 02/11/2019 08:00",
      "value": {
        "currency": "EUR",
        "amount": 3
      },
      "localValues": [
        {
          "currency": "SEK",
          "amount": 30
        },
        {
          "currency": "NOK",
          "amount": 30
        }
      ],
      "points": 100,
      "redeemed": false,
      "redeemedOn": null
    }
  ],
  "promotions": [
    {
      "id": "27c03506-89d6-4023-a158-c0bb0dc09e58",
      "externalId": null,
      "type": "Multichannel",
      "name": "Spring Campaign",
      "expiresOn": null,
      "heading": "Spring Campaign",
      "description": "Dear customer, The spring is here, time for updating your wardrobe! Please enjoy the following spring time promotion. With love",
      "redeemed": false,
      "redeemedOn": null,
      "imageUrl": null,
      "link": null,
      "redemptionChannels": [
    {
      "id": "75992b07-b287-4417-8cb8-adba010fdaf8",
      "externalId": null,
      "type": "Multichannel",
      "name": "20% off VIP offer!",
      "expiresOn": null,
      "heading": null,
      "description": null,
      "redeemed": false,
      "redeemedOn": null,
      "imageUrl": null,
      "link": null,
      "redemptionChannels": [
        {
          "type": "POS",
          "valueType": "PERCENT",
          "value": 20,
          "instruction": null
        },
        {
          "type": "ECOM",
          "valueType": "EXTERNALOFFER",
          "value": "VIP20PERCENT",
          "instruction": null
        }
      ]
    }
  ]
}

Changes going from API v2 to v3

Changes were made to this endpoint for API v3.

See the full list of changes

One important change to note is that in v3 a contact’s total points (bonus points) are no longer returned from /contactoverview. For v3, this can only be done through a separate GET request to the already existing but slightly changed /point-accounts endpoint. See here for more:

Contacts

Transactions

Orders

Loyalty

Product data

Elevate

Ratings and Reviews

Using /contactoverview with contactId

Using /contactoverview with email

Using /contactoverview with mobilePhone

Using /contactoverview with socialSecurityNumber

Using /contactoverview with customKey

Using /contactoverview with any

Response

Changes going from API v2 to v3

See the full list of changes

Read more about points

​Using /contactoverview with contactId

​Using /contactoverview with email

​Using /contactoverview with mobilePhone

​Using /contactoverview with socialSecurityNumber

​Using /contactoverview with customKey

​Using /contactoverview with any

​Response

​Changes going from API v2 to v3

See the full list of changes

Read more about points

Using /contactoverview with contactId

Using /contactoverview with email

Using /contactoverview with mobilePhone

Using /contactoverview with socialSecurityNumber

Using /contactoverview with customKey

Using /contactoverview with any

Response

Changes going from API v2 to v3