Use Data Ingestion API V3 to import external profile and message data into Sprinklr. The API works with Media Upload API V3, which uploads the source file and provides the URL required by the ingestion request.
This guide is intended for developers who are building integrations to import profile or message data into Sprinklr.
Media Upload is the supporting API that gets your spreadsheet to a public URL in the first place. Data Ingestion does not accept a file — it accepts a fileUrl. Media Upload is how you produce one.
1. POST /api/v3/media/upload → Upload the source file (.csv/.xlsx), receive { url }
2. POST /api/v3/dataIngestion/ingest → Submit and ingestion task { fileUrl: <that url>, ... }, receive { taskId }
→ Sprinklr processes the ingestion taskThe V3 Developer Portal defines POST /dataIngestion/ingest as the operation for submitting an ingestion task and POST /media/upload for uploading media. Both operations require bearer-token and API-key authentication.
Data ingestion is asynchronous. The 200 you get back is an acknowledgement carrying a taskId, not a result. The actual outcome — how many records were created, how many failed, and where to download each set — arrives later at your callbackUrl.
The ingestion request uses the type field to identify the type of data being imported.
For profile and message ingestion, the existing Data Ingestion and Media Upload API V3 guide documents these values:
| Use case | type value | V2 page |
|---|---|---|
| Import profiles | PROFILE or INFLUENCER_PROFILE | Bulk Profile |
| Import messages | LISTENING_MESSAGE | Bulk Messages |
type values are case-sensitive. Define them as constants in your own code.
Before submitting an ingestion task, prepare the template used to map the columns in your source file to Sprinklr fields. The saved template name is provided in the templateName field of the ingestion request.
Neither ingestion type works from a bare spreadsheet. You must first establish a template in the UI that maps your file's column headers to Sprinklr fields. This is a one-time, per-template manual step.
Prepare a profile template:
- Log in to the Sprinklr UI and click Profile within Modern Engagement.
- Click the Import icon on the top right.
- Click Download Excel Template to download the template needed for this API.
- Fill in the profile details in the template and upload the file onto the web.
The existing V3 documentation describes profile ingestion as an upsert: when an existing profile identifier is found, Sprinklr updates the profile; otherwise, it creates a profile.
Prepare a message template:
- Log in to the Sprinklr UI and click First Party Data Ingestion within Modern Research.
- Click Import from Excel on the top right.
- Upload the Excel file from your local machine.
- Enter the unique file name and map the Sprinklr fields to the corresponding file headers used in the Excel file. Save the mapping.
Once you map the file headers within Sprinklr and save the mapping under a unique name, you can reuse the same file shape to import more data. You can reference that template by templateName in every subsequent API call and never repeat the UI step for that file shape.
Each profile has a unique ID. If the system finds a profile with that ID in the spreadsheet it updates the profile; otherwise it creates one. There is no separate update endpoint.
By default, the key is the Sprinklr identifier. You can override this with identifierFields.
Use the following base URL:
https://api3.sprinklr.com/{env}/api/v3The endpoints used in this workflow are:
https://api3.sprinklr.com/{env}/api/v3/media/upload
https://api3.sprinklr.com/{env}/api/v3/dataIngestion/ingestReplace {env} with your assigned Sprinklr environment. For the production environment at app.sprinklr.com, omit the {env} segment from the URL. For information about supported environments and how to identify your environment, see APIs | Sprinklr Developer Portal.
The current V3 API reference identifies the production Data Ingestion endpoint as:
https://api3.sprinklr.com/prod/api/v3/dataIngestion/ingest
Environment-scoped credentials. API keys and access tokens are scoped to a single environment. A key generated for one environment returns
401against another even when the request is otherwise perfect.
Content-store URLs are environment-specific too. The
urlreturned by Media Upload belongs to the environment you uploaded to. You must feed it to the ingestion endpoint in that same environment.
All calls are authenticated with OAuth 2.0. See API Overview for portal registration, API key and secret generation, and the Authorize flow.
Both APIs use bearer-token and API-key authentication.
| Header | Value | Purpose | Required on |
|---|---|---|---|
Authorization | Bearer {{accessToken}} | Authenticates the user with the server | All requests |
Key | {{apiKey}} | Authenticates the application with the server | All requests |
Content-Type | application/json | Declares the request body media type | dataIngestion/ingest |
Content-Type | multipart/form-data; boundary=<calculated when request is sent> | Declares a file upload body | media/upload |
Accept | application/json | Declares the acceptable response type | All requests |
Both Authorization and Key are required on every call. Sending only one returns 401.
For file uploads, let your HTTP client generate the appropriate multipart request when attaching the file.
| Credential | Lifetime |
|---|---|
| Authorization code | 10 minutes |
| API key | No expiry |
| Access token | 30 days by default |
One token pair per API key. Generating a new access token for an API key invalidates the previously issued token and refresh token for that key. Two services sharing one key will knock each other offline. Give each service its own key.
Credential hygiene. Never commit an access token or API key, never paste one into a ticket, and never log the
AuthorizationorKeyheader values. Every credential on this page is a placeholder.
Use Media Upload API V3 to upload the source file.
POST /api/v3/media/uploadThe V3 API reference identifies /media/upload as the operation for uploading one or more media files.
Content store is not Asset Manager. Uploading gives you a stored file and a URL. It does not create a managed asset in the Sprinklr Social Asset Manager. For ingestion that is exactly what you want — you only need the URL. If you want the file to appear in Asset Manager, make a separate Asset Create call.
| Parameter | Required | Type | Description |
|---|---|---|---|
assetType | Yes | String | The type of asset being uploaded, for example file, image, or video |
fileName | Yes | String | The name of the file to upload, including its extension — for example customers.xlsx |
| Field | Required | Description |
|---|---|---|
file | Yes | Source of the uploaded media content |
curl -X POST \
'https://api3.sprinklr.com/{env}/api/v3/media/upload?assetType=file&fileName=customers.xlsx' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}' \
-H 'Accept: application/json' \
-F 'file=@"/path/to/customers.xlsx"'The existing V3 guide documents assetType and fileName as required query parameters and file as the multipart form-data field.
{
"data": {
"id": "608676dbc2952f59abc797af",
"mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"name": "customers.xlsx",
"url": "https://{env}-assets.sprinklr.com/{env}-cdata/DAM/50001/00000000-0000-0000-0000-000000000000-0000000000/customers.xlsx",
"previewUrl": "",
"size": 15511
},
"errors": []
}Use the returned data.url value as fileUrl when you submit the ingestion request.
| Field | Type | Description |
|---|---|---|
id | String | Unique identifier for the uploaded content |
mimeType | String | The asset type and format, for example image/png |
name | String | The file name |
url | URL | The URL of the uploaded content on the Sprinklr platform |
previewUrl | URL | The preview URL of the uploaded content |
size | Integer | The size of the uploaded content in bytes |
width | Integer | Width of the uploaded content. Returned for image and video asset types |
height | Integer | Height of the uploaded content. Returned for image and video asset types |
previewWidth | Integer | Preview width. Returned for the image asset type |
previewHeight | Integer | Preview height. Returned for the image asset type |
previewUrl is an empty string for non-previewable types such as spreadsheets, and populated for images.
Uploading multiple files. V3 exposes a single upload path. Call
POST /api/v3/media/uploadonce per file rather than using the V2/media/upload/multiplepath.
After uploading the source file, submit the ingestion task:
POST /api/v3/dataIngestion/ingestThe path segment is
dataIngestion— camelCase, notdata-ingestion. This is the change most likely to break a V2 integration. See Migrating from V2.
| Field | Type | Required | Description |
|---|---|---|---|
type | String | Yes | Type of ingestion — PROFILE, INFLUENCER_PROFILE, or LISTENING_MESSAGE |
name | String | Yes | Unique task name |
fileName | String | Yes | Name of the file |
fileUrl | String | Yes | URL of the file to load data from — the data.url returned by Media Upload |
templateName | String | Yes | Name of the template to use for ingestion, as saved in the UI |
callbackUrl | String | Yes | Callback URL to receive notification on completion |
importTag | String | Yes | Tag for filtering |
callbackType | String | Required when callbackUrl is provided | Type of callback to use |
callbackUrlHeaders | Object (string → string) | No | Headers sent with the callback request, for authenticating the call into your receiver |
identifierFields | Object (string → array of strings) | No | Your own unique identifiers, used to match existing data instead of Sprinklr identifiers. PROFILE only |
id | String | No | Task-related identifier |
ingestionTaskId | String | No | Existing ingestion task identifier |
status | String | No | Ingestion-task status |
externalSourceType | String | No | External-source type |
credentialsId | String | No | Credentials identifier |
additional | Object | No | Additional task information |
Send all eight of the fields marked Required above on every call.
fileNameandimportTagare easy to omit if you are porting a V2 payload — include both.
curl -X POST \
'https://api3.sprinklr.com/{env}/api/v3/dataIngestion/ingest' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"type": "PROFILE",
"name": "crm-profile-import",
"fileName": "customers.xlsx",
"fileUrl": "https://{env}-assets.sprinklr.com/{env}-cdata/DAM/50001/00000000-0000-0000-0000-000000000000-0000000000/customers.xlsx",
"importTag": "crm-nightly",
"templateName": "crm-profile-template",
"callbackUrl": "https://your-host.example.com/hooks/sprinklr-ingest",
"callbackType": "PUBLIC_URL",
"callbackUrlHeaders": {
"X-Webhook-Token": "{{callbackSecret}}"
},
"identifierFields": {
"PARTNER_CUSTOM_PROPERTIES": [
"crm_customer_id"
]
}
}'The V3 API schema requires type, name, fileName, fileUrl, templateName, and callbackUrl.
curl -X POST \
'https://api3.sprinklr.com/{env}/api/v3/dataIngestion/ingest' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"type": "LISTENING_MESSAGE",
"name": "reviews-import-2026-09-02",
"fileName": "messages.xlsx",
"fileUrl": "https://{env}-assets.sprinklr.com/{env}-cdata/DAM/50001/00000000-0000-0000-0000-000000000000-0000000000/messages.xlsx",
"importTag": "reviews-archive",
"templateName": "reviews-template",
"callbackUrl": "https://your-host.example.com/hooks/sprinklr-ingest",
"callbackType": "PUBLIC_URL"
}'The only differences from the profile call are type and the absence of identifierFields.
{
"data": "{\"taskId\":\"6033961866934b5708a5f90a\"}",
"errors": []
}
datais a JSON-encoded string, not an object. The value is"{\"taskId\":\"...\"}"— a string containing escaped JSON. Parse it twice: once for the response envelope, then again for the inner payload.
envelope = response.json()
inner = json.loads(envelope["data"]) # second parse — required
task_id = inner["taskId"]Store the taskId. It is your only correlation handle, and it reappears as the id on the callback payload.
The identifierFields object lets an integration provide unique identifiers used to find existing data instead of relying only on Sprinklr identifiers. The current V3 API schema includes identifierFields as an optional object.
Example:
{
"identifierFields": {
"PARTNER_CUSTOM_PROPERTIES": [
"crm_customer_id"
]
}
}Use this option only when the identifier configuration for your ingestion workflow supports it.
A successful Data Ingestion request uses the standard V3 response envelope. The current V3 reference defines data as an object, accompanied by errors and metadata.
{
"data": {},
"errors": [],
"metadata": {}
}Use the task information returned by the service to correlate the submitted ingestion with subsequent processing.
The ingestion request includes a required callbackUrl, which the V3 API reference describes as the URL used to receive a notification on successful ingestion. Optional callbackUrlHeaders can also be supplied.
Configure the callback endpoint before submitting an ingestion request and use the task identifier returned by the ingestion service to correlate the callback with the source request.
| HTTP code | Scenario |
|---|---|
200 OK | Success. Ingestion returns a taskId; upload returns content metadata |
400 Bad Request | Missing required field, unknown type, malformed multipart body, or unreachable fileUrl |
401 Unauthorized | Invalid or missing Authorization token or Key header |
403 Forbidden | Caller lacks permission to ingest data or upload media |
404 Not Found | Wrong path — most often data-ingestion instead of dataIngestion. Also an unknown templateName |
| Field | Type | Description |
|---|---|---|
id | String | Error identifier |
code | Integer | Numeric error code |
message | String | Error key, for example account.not.found |
| Symptom | Likely cause | Fix |
|---|---|---|
404 on every ingestion call | Using data-ingestion (kebab) instead of dataIngestion (camelCase) | Change the path. This is the number-one V3 migration failure |
400 naming fileName | fileName is required in V3 | Add fileName |
400 naming importTag | importTag is required | Add importTag |
400 on type | Value not one of PROFILE, INFLUENCER_PROFILE, LISTENING_MESSAGE, or wrong case | Use one of the three exactly |
400 on templateName | Template does not exist, or the name does not match exactly | Re-check the name saved in the UI |
Client fails deserializing data | Ingestion returns data as a JSON-encoded string, not an object | Parse twice |
400 on multipart upload | Content-Type hard-coded without a matching boundary | Let the HTTP client set the header |
Upload succeeds, ingestion 400s on fileUrl | The content-store URL is environment-specific | Upload and ingest in the same {env} |
| Callback never arrives | Receiver does not return 200 to an empty POST, or the TLS certificate is invalid | Verify both |
| Callback arrives, results look wrong | You are reading the synchronous response, not the callback payload | Per-record counts are callback-only |
| Cannot tell which rows failed | The synchronous response has no per-record data | Download failedFileUrl — the reason is in the last column |
401 with all headers present | Credentials belong to a different environment | Regenerate for the target environment |
401 after previously working | Token expired (30-day default), or a second token was issued for the same key | Refresh; one key per service |
| Uploaded file not in Asset Manager | The content store is not Asset Manager | Call Asset Create separately |
Update integrations that use the V2 Data Ingestion endpoint to use the V3 path.
- POST /api/v2/data-ingestion/ingest
+ POST /api/v3/dataIngestion/ingestFor V3, the Data Ingestion namespace is dataIngestion. The current V3 endpoint is explicitly published as POST /dataIngestion/ingest.
Media uploads use:
POST /api/v3/media/upload
When migrating, also review your request against the V3 schema rather than assuming V2 and V3 have identical request and response contracts.
Export changed customers to .xlsx, then:
POST /api/v3/media/upload?assetType=file&fileName=customers-2026-09-02.xlsx
→ data.url
POST /api/v3/dataIngestion/ingest
{ "type": "PROFILE", "name": "crm-sync-2026-09-02", "fileName": "customers-2026-09-02.xlsx",
"fileUrl": "<data.url>", "importTag": "crm-nightly",
"templateName": "crm-profile-template",
"callbackUrl": "https://your-host.example.com/hooks/sprinklr-ingest",
"callbackType": "PUBLIC_URL" }
→ { "taskId": "..." }Because profile ingestion upserts, the same job handles both new and changed customers. Use a dated name so tasks are traceable, and a stable importTag so all runs of this job can be filtered together.
If you do not want to store Sprinklr IDs, add identifierFields so matching happens on your key instead:
"identifierFields": { "PARTNER_CUSTOM_PROPERTIES": ["crm_customer_id"] }PROFILE only, and PARTNER_CUSTOM_PROPERTIES is the only supported key.
Load an archive of support tickets or reviews as LISTENING_MESSAGE so Sprinklr AI, listening, and automation apply to them and they appear alongside native data in the same dashboards.
Message ingestion requires a template mapped through First Party Data Ingestion in Modern Research.
Do not treat the 200 as success. On callback:
if failedRecordsCount > 0:
download failedFileUrl # last column = failure reason
fix rows, re-upload, re-ingest
download successfulFileUrl # last column = Sprinklr ID → store the mappingsuccessfulFileUrl is the only way to map your rows back to Sprinklr IDs.
Make name unique per run — a timestamp or UUID — and rely on the upsert key (the Sprinklr ID, or identifierFields) to prevent duplicate records if a job is replayed.
Media Upload is useful independently of ingestion. Upload once, then reference data.url wherever the platform accepts a media URL. Remember that this does not create an Asset Manager asset — call Asset Create if you need that.
Path and namespace
- The path is
dataIngestion, camelCase.data-ingestionreturns404. - Keep the base path in one configuration constant.
Request body
- Send
type,name,fileName,fileUrl,templateName,callbackUrl, andimportTagon every call. typeacceptsPROFILE,INFLUENCER_PROFILE, andLISTENING_MESSAGE, and is case-sensitive.- Never send an empty
fileUrl.
Asynchrony
- The
200is an acknowledgement, not a result. Per-record outcomes arrive only at the callback. - Your callback receiver must return
200to an empty POST and present a valid TLS certificate. - Always download
failedFileUrlwhenfailedRecordsCount > 0; the reason is in the last column. - Store the
taskId— it is theidon the callback payload and your only correlation handle.
Response parsing
- Ingestion returns
dataas a JSON-encoded string. Parse twice. - Media Upload returns
dataas a real object. The two endpoints differ. - Always inspect the
errorsarray, not just the HTTP status. startTimeandcompletionTimeare epoch milliseconds.
Media upload
- Let your HTTP client set the multipart
Content-Typeboundary. - The form field name is
file. - Send
fileNamewith its extension. - Content-store URLs are environment-specific — upload and ingest in the same
{env}. - Uploading does not create an Asset Manager asset.
Templates and permissions
- The template must be created in the UI first; this cannot be automated through these APIs.
templateNamemust match exactly.- A
403is a permission gap, not a malformed request.
Volume
- Add backoff around bulk jobs, and keep individual files to a size your own pipeline can re-drive on failure.