API Reference

The Data Talks API provides a way for our customers to integrate and send data from multiple systems through a single endpoint. The supported integration can be enabled or disabled for customers, and the way data is organized and sent to the different systems is controlled via mappings. This documentation aims to describe and explain what the currently supported integrations are, how to authenticate and use the API, and how to define the mappings for an integration.

OpenAPI (Swagger) Specification

https://api.datatalks.se/index.html

API Endpoints

v1

https://datatalks.atlassian.net/wiki/spaces/PI/pages/875102209/Datatalks+API

v2

API EndpointAPI URL
Profileshttps://api.datatalks.se/v2/profiles
Eventshttps://api.datatalks.se/v2/events
Inventoryhttps://api.datatalks.se/v2/inventory
API Endpoints

Staging API

If you want to test API out in a safe environment you can use the staging endpoints:

API EndpointAPI URL
Profileshttps://staging.api.datatalks.se/v2/profiles
Eventshttps://staging.api.datatalks.se/v2/events
Inventoryhttps://staging.api.datatalks.se/v2/inventory
Staging API Endpoints

Salesmanago Integration (v2)

If the payload is supposed to be sent to Salesmanago, groupKey field must be filled (see v1 documentation).

A group key is our internal way to group your integrations. This is useful if you have multiple brands or markets and have different accounts in the integration systems and you want to send separate API requests to them. In case you don’t have such, you will have only one group_key to work with. Make sure that the group_key is sent in every request.

Requests and Responses

datatalksId - optional parameter field (see Basic Concepts section).

Profiles – Example POST Request

{
"type": "person",
"groupKey": "main_group",
"data":{
		"customer_id":12345,
		"first_name":"Juliana",
		"last_name":"Crane",
		"email":"juliana.crane@fake.com",
		"age":32,
		"postal_code":"111 17",
		"address":"Kungsbroplan 3",
		"city":"Stockholm",
		"country":"Sweden",
		"is_member":"Yes",
		},
	"datatalksId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Events – Example POST Request


{
"type": "purchase_ev",
"groupKey": "main_group",
"data":{
		"event_id":"848ASHC382392AHSJA",
		"event_type":"Purchase",
		"event_datetime":"2021-03-18 11:35:24",
		"customer_id":12345,
		"status":"Confirmed",
		"payment_method":"Debit Card",
		"total_purchase_amount":"123.75",
		"total_purchase_discounted_amount":"112.00",
		"currency":"Euros",
		"online_purchase":"No",
		"Member_points_before_purchase":4561,
		"purchase_points":112
		},
	"datatalksId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Inventory – Example POST Request

{
"type": "product_a",
"groupKey": "main_group",
"data":{
		"item_id":"AB-192910",
		"inventory_type":"Product",
		"item_modified":"2020-12-03 17:23:21",
		"name":"Milk",
		"category":"Dairy Products",
		"subcategory":"Cow Milk",
		"brand":"Milky",
		"size":"1.0L",
		"type":"Light"
		},
	"datatalksId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Response Example

{
    success = true/false,
    messages = [""],
    requestId = requestId,
    datatalksId = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,
    key = yourAwsKey,
}

Response Codes

Response CodeDescription
200The request is completed successfully
400Bad request. Please see the response messages field
403Missing Authentication Token
500Internal server error: please contact us. If the response mentions requestID, make sure it is included in your report
Response Codes

Basic Concepts

Data Talks ID

Datatalks ID is a UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) that is automatically generated, stored and returned for every entity processed by API.

Identifying a customer

Data Talks should create a Datatalks ID for every customer that arrives in our systems through API, files, or third-party systems. The Datatalks ID is the master id and all potential IDs coming from the source systems should belong to this one as secondary IDs. Different customers can have different requirements when it comes to the Unique Id that they can send to us. Some have email as the unique id while some of them have a CRM id as the unique identifier.

Custom Mappings

You can describe (map) the entities (Events, Profiles, and Inventories – see Endpoints). As long as it suits the data types that Data Talks CDP accepts, you can define as many fields as you like and the way they will look like. Therefore the following can be defined: the name of the source field, the name of the field to appear in Data Talks CDP, the data type (respecting the limitations), and the format of the data.

Mappings should be defined per each entity (datapoint type) on the onboarding stage, before start using API.

Any unmapped payload field will be ignored by default.

Any missing field will lead to 400 – Bad Request API response. Except for the fields marked as Optional.

Authentication

To build the Authorization header you will need AWS IAM account credentials – ACCESS_KEY_ID and SECRET_ACCESS_KEY. When requesting access to our API an account will be created for you by our team and the credentials will be sent to you.

The authentication of the API is implemented via AWS IAM. When making an API request you will have to authenticate via AWS Signature Version 4. Here is an example of an Authorization header done with AWS Signature Version 4:

Authorization: AWS4-HMAC-SHA256
Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/execute-api/aws4_request,
SignedHeaders=host;range;x-amz-date,
Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024

To build the Authorization header you will need an AWS IAM account credentials – ACCESS_KEY_ID and SECRET_ACCESS_KEY. When requesting access to our API an account will be created for you by our team and the credentials will be sent to you.

Implementing Authentication

There is an AWS SDK for the most popular development stacks (.NET, Java, Javascript, Ruby, Python, etc.). Some of the SDKs might not provide the Signature Version 4 out of the box, so you might need to implement it by yourself. Browse the articles under this section to see examples of signing requests with Signature Version 4.

Additional Resources

Signature Version 4 Signing Process

Powered by BetterDocs

Arrow-up