Skip to main content

​
Getting Started

You can import your data residing in your server to the Zeotap CDP by following the step-by-step instructions provided:
  1. To begin with, create a Server-to-Server source within Zeotap CDP
  2. Next, set up the Server-to-Server source to transfer either real-time or batch data as per your requirement

​
Step 1 - Create a Server-to-Server Source Within Zeotap CDP

Perform the following steps to create a Server-to-Server Source in Zeotap CDP App:
1
Navigate to the Sources application in the Zeotap CDP App.
2
Click CREATE SOURCE.
3
Choose Server to Server as the Category.
4
Click HTTP API as the Data Source.
5
In the window that appears, provide the following details:a. Enter a short and descriptive name for the Source.b. Choose the region of upload where the data needs to be stored. Learn morec. Under Data Entity, depending on the type of data that you want to ingest, choose either Customer Data or Non Customer Data and proceed with the source creation. Learn more
6
Click + Create Source. The created source appears on the source listing page. At this point, the source is assigned the Created status, as shown in the below example.
7
In the IMPLEMENTATION DETAILS tab, you can find information such as the write key and API URL (Zeotap CDP Server’s API endpoint).Use this information to make API calls for sending data to Zeotap CDP server.
Note:Note that you need to wait 30 minutes before using this write key to make API calls.

​
Step 2 - Set up the Server-to-Server Source to Transfer Data Using HTTP API

After creating a Server-to-Server source successfully, you can transfer data through one of the following methods:
  • Using Real Time API - This enables immediate communication and data exchange between your server and Zeotap CDP’s server. Data is processed and transferred with minimal delay, ensuring near-instant updates and responsiveness. Below is a skeletal payload structure.
Code
{
  "event": {
    ...
    
  },
  "page": {
    ...
    
  },
  "user": {
    ...
    
  },
  "consent": {
    ...
    
  },
  "device": {
    ...
    
  }
}
  • Using Batch API - This allows multiple requests to be bundled or grouped together and submitted as a single batch for processing. Instead of sending individual requests one by one, a batch API enables the client to efficiently send a collection or batch of requests in a single API call.
The set-up and authorisation process for sending data in batches is the same as Real Time API. However, the events must be batched as events object with an array of events inside the object. Below is a skeletal payload structure.
Code
{
  "events": [ 
    { 
      "event": {...}, 
      "user": {...} 
    }, 
    { 
      "event": {...}, 
      "user": {...} 
    }, 
  ] 
}

​
Data Transfer in Server to Server Integration

You can transfer data from your server to Zeotap CDP in real time or in batches, depending on your requirement. The setup and authorization process for sending data remain the same. However, the key difference lies in batching the events. Perform the following steps to transfer data in the Server-to-Server integration:
1
Once the Server to Server source is created in the Sources application, navigate to the IMPLEMENTATION DETAILS tab and copy the API URL and Write_Key of the created source.
2
Open an API tool such as Postman and create a HTTP POST request with the following details:a. Provide the API URL copied earlier as the endpoint URL for making API calls. The region and eventType are displayed in the Params section as shown below.
b. Under the Authorization tab, ensure that the Auth Type is set to Inherit auth from parent.
c. Under the Headers tab, perform the following steps:i. Set the content-Type header to application/JSON and Charset to UTF-8.ii. Set the Authorization header to Basic base64(w_k:<your_write_key>). For example, if your assigned write key is fc3ab803-5762-44d3-88d3-7fbc94bca074, then perform the following steps before entering it in the Authorization header:
  1. Add the prefix w_k: to the write key without any spaces, resulting in w_k:fc3ab803-5762-44d3-88d3-7fbc94bca074
  2. Encode the modified key w_k:fc3ab803-5762-44d3-88d3-7fbc94bca074 using Base64 encoding. In this case, the encode value is d19rOmZjM2FiODAzLTU3NjItNDRkMy04OGQzLTdmYmM5NGJjYTA3NA==
  3. Combine the string “Basic” followed by a space and the Base64-encoded value as shown below. Basic d19rOmZjM2FiODAzLTU3NjItNDRkMy04OGQzLTdmYmM5NGJjYTA3NA==
  4. Paste the resulting string in the Authorization header.
d. Under the Body tab, paste a valid JSON Payload as shown below.
JSON
{
  "page": {
    "url": "https://www.carseller.com/"
    
  },
  "user": {
    "age": 35,
    "userId": "1234567890",
    "country": "ESP",
    "email": "example@mail.com",
    "test": "true",
    "first_name": "Name",
    "last_name": "Surname"
    
  },
  "consent": {
    "marketing": "Yes",
    "personalisation": "Yes",
    "email": "Yes"
    
  }
}
3
Once all the inputs are entered, click Send. The API returns a 204 No Content response if the API call is successful. Once the API request is successful, the data is transferred to Zeotap CDP. Use the PREVIEW tab to see incoming data. Note that at this point, the source transitions to the INTEGRATED state.
4
If you receive a 400 Bad Request response, follow these troubleshooting steps:a. In Params, ensure that a valid region is added, like ‘EU’ and the eventType is set to ‘s2s’.b. Verify the endpoint URL and headers. Make sure the Authorization header follows the required prerequisites.c. Validate the JSON payload body for correctness.For any assistance, reach out to the Zeotap Support team at support@zeotap.com.

​
JSON Payload Structuring Guidelines

We recommend structuring the payload body based on the type of data you want to send.
  • Events data – All event-related information is recommended to be sent in the event object. The eventName and eventTimestamp objects are considered as the primary data points for sending the event-related information. Other attributes relating to the event, such as a user action (for example, "discountSelected": "SPL25") or an event property (for example, "cartVal":100) can be sent within the event object.
  • Page data – All page-related meta-information such as the URL, referrer, category, domain and path can be sent in the page object.
  • User data – All user identifiers and profile information can be sent in the user object. If you want to send the profile information against the relevant ID(s), then set the corresponding eventName as setUserProperties.
  • Consent data – All consents provided by the customer per purpose, along with regulation can be sent in the consent object.
  • Device data – All device-related information such as OS, browser, device model and so on can be sent in the device object.
  • User Identification – Zeotap cannot fetch cookies or MAIDs automatically in the server-to-server calls. Therefore, all data must contain at least one user ID.
    • For data about the registered or known users, always attach the corresponding email, loginID or cell phone number hashes in the specific events along with device-based IDs if any.
    • For anonymous users, device-based IDs such as first-party cookies, third-party cookies or MAIDs must be attached.
  • Country Identification – Zeotap cannot infer the country of the user automatically from the IP Address in the server-to-server calls. Therefore, all data must contain the country information. If the country information is absent, the same is mandated to be hardcoded when setting up the mapping and ingestion in your Sources account.
The set-up and authorisation process for sending data in batches is the same as Real Time API. However, the events must be batched as events object with an array of events inside the object.
Note:Zeotap supports flexible and configurable mapping of most JSON structures from external systems. Ensure that your data includes the following:
  • User Information: Details about the user and their identifier(s).
  • Personal Information: Relevant personal details.
  • Event Data: All information about the event, such as the event name and timestamp. Use either a UNIX timestamp or a fully time-zone-qualified format according to ISO 8601 (For example, 2024-09-05T11:02:44Z, 2024-09-04T23:02:44−12:00, 2024-09-05T11:02:44+00:00).
For the data format, use types that match the provided data:
  • Numeric for numbers
  • Strings for textual data
  • Booleans for true/false values
  • JSON objects for structured data
  • Arrays for lists
  • Null where applicable

​
Sample API Requests

​
Sample Payload Request for Real Time API

Below is an example of a sample payload request for Real Time API.
JSON
{
  "page": {
    "url": "https://www.carseller.com/"
  },
  "user": {
    "age": 35,
    "userId": "1234567890",
    "country": "ESP",
    "email": "example@mail.com",
    "test": "true",
    "first_name": "Name",
    "last_name": "Surname"
  },
  "consent": {
    "marketing": "Yes",
    "personalisation": "Yes",
    "email": "Yes"
  }
}

​
Sample Payload Request for Batch API

Below is an example of a sample payload request for Batch API.
JSON
{
  "events": [
    {
      "user": {
        "visitorId": "123436",
        "email": "example1@gmail.com",
        "contactId": "con12346"
      },
      "event": {
        "eventType": "View Product",
        "timestamp": "1687113601",
        "userAgent": "Mozilla/5.0 (Windows; U; Windows NT 5.2) AppleWebKit/533.1.5 (KHTML, like Gecko) Version/5.0.1 Safari/533.1.5",
        "sessionId": "7afde13d-f164-4d50-0519-6c72e32f45e8",
        "productName": "Phone",
        "cartQuantity": "",
        "paymentType": "Cash",
        "orderId": "OD212",
        "amountReceivedCoupons": " 1.893,76 € ",
        "birthdate": "1880-05-21",
        "addressLine1": "Na Chmelnici 9",
        "countryCode": "DEU"
      },
      "consent": {
        "gdpr_consent_marketing": "yes"
      },
      "page": {
        "eventUrl": "https://www.example.com/Esmara",
        "pageTitle": "Phone"
      }
    },
    {
      "user": {
        "visitorId": "1234567",
        "email": "example2@gmail.com",
        "contactId": "con12348"
      },
      "event": {
        "eventType": "addToCart",
        "timestamp": "1689113601",
        "userAgent": "Mozilla/5.0 (Windows; U; Windows NT 5.2) AppleWebKit/533.1.5 (KHTML, like Gecko) Version/5.0.1 Safari/533.1.5",
        "sessionId": "7afde13d-f164-4d50-0519-6c72e00005e8",
        "productName": "Sneakers",
        "cartQuantity": "",
        "paymentType": "Credit",
        "orderId": "OD472",
        "amountReceivedCoupons": " 493,76 € ",
        "birthdate": "1990-05-21",
        "addressLine1": "Na Chmelnici 9",
        "countryCode": "DEU"
      },
      "consent": {
        "gdpr_consent_marketing": "yes"
      },
      "page": {
        "eventUrl": "https://www.example.com/Esmara",
        "pageTitle": "Sneakers"
      }
    },
    {
      "user": {
        "visitorId": "1234568",
        "email": "example3@gmail.com",
        "contactId": "con12380"
      },
      "event": {
        "eventType": "Checkout",
        "timestamp": "1687413601",
        "userAgent": "Mozilla/5.0 (Windows; U; Windows NT 5.2) AppleWebKit/533.1.5 (KHTML, like Gecko) Version/5.0.1 Safari/533.1.5",
        "sessionId": "7afde13d-f164-4d50-0519-6c11132f45e8",
        "productName": "Chair",
        "cartQuantity": "",
        "paymentType": "Cheque",
        "orderId": "OD714",
        "amountReceivedCoupons": " 2.013,70 € ",
        "birthdate": "1987-05-21",
        "addressLine1": "Na Chmelnici 9",
        "countryCode": "DEU"
      },
      "consent": {
        "gdpr_consent_marketing": "yes"
      },
      "page": {
        "eventUrl": "https://www.example.com/Esmara",
        "pageTitle": "Chair"
      }
    }
  ]
}

​
Performance

​
Query Per Second

We have an auto-scaling cluster. Therefore, we can support high Query Per Second (QPS). Reach out to your Zeotap POC to notify you about the set-up in advance, so that the same can be set up for active monitoring. This is especially important if you expect QPS to exceed 200.

​
Batch Size

When setting up batched events, ensure that the payload size does not exceed 20 MB.

​
Status Codes and Responses

Response CodeDescription
204 No Content The request is successful.
400 Bad Request The error is published to the x-zeo-debug header. For example, this could contain the error details as the value. Learn more
Once you have created and implemented a Server-to-Server source, map the ingested data in the Catalogue. Below are some quick links to help with mapping.
  • To learn how to map the Catalogue for Customer Data (CE), refer here.
  • To learn how to map the Catalogue for Non-Customer Entity (NCE) data, refer here.
  • To learn how to add a Non-Customer Entity (NCE) attribute in the Catalogue, refer here.
  • To learn about Join Key Enricher and how to configure it, refer here.
Last modified on February 26, 2026