API Documentation For Testing Records Data Ingestion

This document provides guidance on using Zencity’s API to ingest records data into our Test environment. The API allows you to push data into our system at any time, with support for batching multiple records in a single request.

Once testing is successfully completed, we will provide you with credentials for our Production environment.

API Endpoint

Environment: STAGING
Method: POST
URL:

https://staging-social-listener.zencity.io/api/genericWebhook/<data_source_id>

Authentication

Include the following header in your request:

X-Auth-Token: <your_token_here>

⚠️The data_source_id and X-Auth-Token will be provided by the Zencity team. These are sensitive credentials and must be kept secure.

Request Body

Zencity's API accepts a JSON string request that can be composed in two different formats:

1. A flat one leveled array of objects:

[
  { ... },
  { ... },
  ...
]

2. Multileveled object with a designated key (commonly items):

{
  "items": [
    { ... },
    { ... },
    ...
  ]
}

If you use the dictionary format, the Zencity team will pre-configure the expected key (e.g., "items").

Data Mapping

Before integration, Zencity will work with you to map your record fields names to our internal schema. This ensures proper parsing and processing of the incoming data.

Example Request

POST <https://staging-social-listener.zencity.io/api/genericWebhook/12345>
// headers
X-Auth-Token: bfb14b59dfb52fcc4d385e36d8e3314c5f6849dab0412df16537b6efde1c0d2
// body:
{
  "items": [
    {
      "REQUEST_ID": "123456",
      "REFERENCE_ID": "REF-7890",
      "REQUEST_TYPE": "TypeA",
      "REQUEST_CATEGORY": "CategoryX",
      "STATUS": "Closed",
      "DESCRIPTION": "Request description here.",
      "DETAIL": "Detailed information about the request.",
      "DATE_COMPLETED": "2024-08-05T14:48:00",
      "DATE_RECEIVED": "2024-08-01T09:30:00",
      "NAME": "John Doe",
      "GIVEN_NAMES": "John Michael",
      "MOBILE_PHONE": "+1234567890",
      "EMAIL_ADDRESS": "john.doe@example.com"
    }
  ]
}