Profile Integration Specification

The Profile Integration APIs provide synchronous and asynchronous options to upload and update subscriber records in Msgkart.

Run in Postman

---

Global API Configuration

Parameter	Required On Every Request	Value
Base URL	Yes	https://{{msgkart_host}}
Header	Yes	x-api-key: {{api_key}}
Header	Yes	Content-Type: application/json

---

Available Endpoints

1. Direct Profile Upload API (POST /api/v3/profile-upload/contacts)
   • Synchronous upload of subscriber profiles directly in the request body.
2. Bulk Profile Upload API (POST /api/v3/profile-upload/contacts/bulk)
   • Asynchronous import of large profile datasets via a presigned URL.

---

Standard Profile Body Schema

The request body must contain a profile array. The specification's direct-upload example shows a single object, but its validation guidance explicitly requires an array ({"profile":[...]}); use the array form. Field names are case-sensitive.

Field	Type	Required	Description
phone	string	REQUIRED	Subscriber's mobile number (e.g. "917415908509"). Record is rejected if missing or invalid.
countrycode	string	Optional	ISO country code. Defaults to IN if omitted.
name	string	Optional	Full name of the subscriber.
age	integer	Optional	Age of the subscriber as an integer.
gender	string	Optional	Allowed values: male, female, or other.
dob	string	Optional	Date of birth. The field description specifies DD/MM/YYYY, but the sample request uses a Unix-epoch integer; confirm the accepted format with Msgkart before sending this field.
businesssubscriberid	string	Optional	Your system's unique user or customer ID (e.g. "CUST-98712").
* (custom fields)	any	Optional	Any other custom attribute (e.g., city, tier)

---

Status & Error Codes

The following responses are specified for the profile upload endpoints:

HTTP Status Code	Condition	Resolution
200 OK	Request processed or initiated	Ingestion completed, or the background job started.
400 Bad Request	Missing profile array	Format the request as {"profile": [...]}.
400 Bad Request	Missing url field	Required for bulk upload; provide a non-empty URL.
400 Bad Request	Invalid file URL	The URL scheme must be http or https.
401 Unauthorized	Missing x-api-key header	Include the x-api-key header on every request.
401 Unauthorized	Invalid API key	The key is incorrect or deactivated; contact support to rotate it.
500 Internal Server Error	Failed to fetch and store file	The presigned URL may have expired, be unauthorized, or return a non-200 response. Verify that it is readable.

Run in Postman