Get enriched profile for personalization
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.
Caution
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 (/contacts/{contactId}/promotions for example).
Caution
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 send contactType if you want, like this, 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 and then customKey.
For example:
GET /api/v3/contactoverview?contactType=ecom&any=jane.doe%40gmail.com
GET /api/v3/contactoverview?contactType=contact&any=999888777
With the any parameter, the contactType must also be sent.
Caution
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
Response data example
{
"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 v2 to v3
Changes were made to this endpoint for v3. See here for the full list of changes.
Important
One important change 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.