Skip to main content
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, allowing for a more qualitative dialogue with a sales person
  • 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 which target audience (profile) the current customer belongs to
This is all achieved through the /contactoverview endpoint. The data from the /contactoverview 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.

​
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
{
  "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 here for 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.