Syncing Customer Data Via API

Sending Customer Data to CitrusAd

To send customer data to CitrusAd, use a command similar to the one below. Note that the data in the "customers" field is dummy data and is provided here only as an example.

All fields in the "Customer" object are optional. If you push a "Customer" object without any values in the fields, a new id will be created. Do not specify an ID if you are creating Customer objects.

All values in the targetingData field are arbitrary and configurable by the retailer. For more info, look at the reference page.

HTTP
cURL
HTTP
POST $BASE_URL/v1/customers HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
"customers": [
{
"id": "string",
"teamId": "string",
"yearOfBirth": "number",
"gender": "string",
"suburb": "string",
"postcode": "number",
"targetingData": {
"targetKey": "targetValue",
"targetKey2": "targetValue2"
}
}
]
}
cURL
curl -iX POST "$BASE_URL/v1/customers" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
"customers": [
{
"id": "string",
"teamId": "string",
"yearOfBirth": "number",
"gender": "string",
"suburb": "string",
"postcode": "number"
}
]
}'

If successful, you will get the following object returned:

HTTP
cURL
HTTP
HTTP/2 200
{
"customers": [
{
"targetingData": {
"customer_type": "string"
},
"gender": "string",
"teamId": "string",
"postcode": "number",
"suburb": "string",
"id": "string",
"yearOfBirth": number
}
]
}
cURL
{
"customers": [
{
"targetingData": {
"customer_type": "string"
},
"gender": "string",
"teamId": "string",
"postcode": "number",
"suburb": "string",
"id": "string",
"yearOfBirth": number
}
]
}

A mock version can be seen below:

HTTP
cURL
HTTP
POST $BASE_URL/v1/customers HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
"customers": [
{
"id": "54358f9b-bbb9-49fb-93fe-3ad481ce564",
"teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
"yearOfBirth": "1965",
"gender": "Other",
"suburb": "Islington",
"postcode": "0000",
"targetingData": {
"customer_type": "Corporate"
}
}
]
}
cURL
curl -iX POST "$BASE_URL/v1/customers" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
"customers": [
{
"id": "54358f9b-bbb9-49fb-93fe-3ad481ce564",
"teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
"yearOfBirth": "1965",
"gender": "male",
"suburb": "Islington",
"postcode": "0000"
}
]
}'

If successful, you will get the following object returned:

HTTP
cURL
HTTP
HTTP/2 200
{
"customers": [
{
"targetingData": {
"customer_type": "Corporate"
},
"gender": "Other",
"teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
"postcode": "0000",
"suburb": "Islington",
"id": "8519ac3b-836e-45e8-8b91-368151e89f90",
"yearOfBirth": 1965
}
]
}
cURL
{
"customers": [
{
"targetingData": {
"customer_type": "Corporate"
},
"gender": "Male",
"teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
"postcode": "0000",
"suburb": "Islington",
"id": "8519ac3b-836e-45e8-8b91-368151e89f90",
"yearOfBirth": 1965
}
]
}

Syncing Multiple Customers

If you are syncing multiple customers, you can send up to 100 items per request as a batch. The number of requests that you can make is not limited.

The order of the Customer payload pushed is the same order as the result returned. This makes it possible for the data to be congruent with the Customer representation that the integrator maintains in their backend.

HTTP
cURL
HTTP
POST $BASE_URL/v1/customers HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
"customers": [
{
"id": "string",
"teamId": "string",
"yearOfBirth": "number",
"gender": "string",
"suburb": "string",
"postcode": "number",
"targetingData": {
"targetKey": "targetValue",
"targetKey2": "targetValue2"
}
},
{
"id": "string",
"teamId": "string",
"yearOfBirth": "number",
"gender": "string",
"suburb": "string",
"postcode": "number",
"targetingData": {
"targetKey": "targetValue",
"targetKey2": "targetValue2"
}
}
]
}
cURL
curl -iX POST "$BASE_URL/v1/customers" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
"customers": [
{
"id": "string",
"teamId": "string",
"yearOfBirth": "number",
"gender": "string",
"suburb": "string",
"postcode": "number",
"targetingData": {
"targetKey": "targetValue",
"targetKey2": "targetValue2"
}
},
{
"id": "string",
"teamId": "string",
"yearOfBirth": "number",
"gender": "string",
"suburb": "string",
"postcode": "number",
"targetingData": {
"targetKey": "targetValue",
"targetKey2": "targetValue2"
}
}
]
}'

If successful, you will get the following object returned:

HTTP
cURL
HTTP
HTTP/2 200
{
"customers": [
{
"targetingData": {
"customer_type": "string"
},
"gender": "string",
"teamId": "string",
"postcode": "number",
"suburb": "string",
"id": "string",
"yearOfBirth": number
},
{
"targetingData": {
"customer_type": "string"
},
"gender": "string",
"teamId": "string",
"postcode": "number",
"suburb": "string",
"id": "string",
"yearOfBirth": number
}
]
}
cURL
{
"customers": [
{
"targetingData": {
"customer_type": "string"
},
"gender": "string",
"teamId": "string",
"postcode": "number",
"suburb": "string",
"id": "string",
"yearOfBirth": number
},
{
"targetingData": {
"customer_type": "string"
},
"gender": "string",
"teamId": "string",
"postcode": "number",
"suburb": "string",
"id": "string",
"yearOfBirth": number
}
]
}

A mock version can be seen below:

HTTP
cURL
HTTP
POST $BASE_URL/v1/customers HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
"customers": [
{
"id": "",
"teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
"yearOfBirth": "1965",
"gender": "Male",
"suburb": "Islington",
"postcode": "0000",
"targetingData": {
"customer_type": "Corporate"
},
{
"id": "",
"teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
"yearOfBirth": "1975",
"gender": "Female",
"suburb": "Islington",
"postcode": "0004",
"targetingData": {
"customer_type": "Corporate"
}
}
]
}
cURL
curl -iX POST "$BASE_URL/v1/customers" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
"customers": [
{
"id": "54358f9b-bbb9-49fb-93fe-3ad481ce564",
"teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
"yearOfBirth": "1965",
"gender": "male",
"suburb": "Islington",
"postcode": "0000"
}
]
}'

If successful, you will get the following object returned:

HTTP
cURL
HTTP
HTTP/2 200
{
"customers": [
{
"targetingData": {
"customer_type": "Corporate"
},
"gender": "Other",
"teamId": "feb219f7-a102-4f96-9a42-e5ef487af6cc",
"postcode": "0000",
"suburb": "Islington",
"id": "8519ac3b-836e-45e8-8b91-368151e89f90",
"yearOfBirth": 1965
},
{
"targetingData": {
"customer_type": "Corporate"
},
"gender": "Other",
"teamId": "feb219f7-a102-4f96-9a42-e5ef487af6cc",
"postcode": "0004",
"suburb": "Islington",
"id": "abb52454-1c1f-4654-b5db-b9a1d622effd",
"yearOfBirth": 1975
}
]
}
cURL
{
"customers": [
{
"targetingData": {
"customer_type": "Corporate"
},
"gender": "Male",
"teamId": "feb219f7-a102-4f96-9a42-e5ef487af6cc",
"postcode": "0000",
"suburb": "Islington",
"id": "8519ac3b-836e-45e8-8b91-368151e89f90",
"yearOfBirth": 1965
},
{
"targetingData": {
"customer_type": "Corporate"
},
"gender": "Female",
"teamId": "feb219f7-a102-4f96-9a42-e5ef487af6cc",
"postcode": "0004",
"suburb": "Islington",
"id": "abb52454-1c1f-4654-b5db-b9a1d622effd",
"yearOfBirth": 1975
}
]
}

Reference

Relevant Context Fields

String

Description

Required?

teamId

Your teamId

Required

your_api_key_here

Your API key

Required

gender

The customer's gender can be Male or Female. Must be capitalised.

Optional

postcode

The customer's postcode.

Optional

suburb

The customer's suburb.

Optional

yearOfBirth

The customer's year of birth.

Optional

targetingData

Contains specific targeting data that can be used for custom targeting. Formatted as "string":"string", such as "member_type":"member","customer_type":"small_business","location_group"

Optional

For a glossary of all terms in the documentation, see the reference.

If you are unsure of the strings displayed on this page. Take a look at the Reference page.