Skip to content

Data Ingestion and Media Upload API V3

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.

Data ingestion uses the following workflow:

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 task

The 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.

Supported ingestion types

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 casetype valueV2 page
Import profilesPROFILE or INFLUENCER_PROFILEBulk Profile
Import messagesLISTENING_MESSAGEBulk Messages

type values are case-sensitive. Define them as constants in your own code.


Before you begin

The template must exist in the Sprinklr UI

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:

  1. Log in to the Sprinklr UI and click Profile within Modern Engagement.
  2. Click the Import icon on the top right.
  3. Click Download Excel Template to download the template needed for this API.
  4. 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:

  1. Log in to the Sprinklr UI and click First Party Data Ingestion within Modern Research.
  2. Click Import from Excel on the top right.
  3. Upload the Excel file from your local machine.
  4. 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.

Profile ingestion is an upsert

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.


Base URL

Use the following base URL:

https://api3.sprinklr.com/{env}/api/v3

The endpoints used in this workflow are:

https://api3.sprinklr.com/{env}/api/v3/media/upload
https://api3.sprinklr.com/{env}/api/v3/dataIngestion/ingest

Replace {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 401 against another even when the request is otherwise perfect.

Content-store URLs are environment-specific too. The url returned by Media Upload belongs to the environment you uploaded to. You must feed it to the ingestion endpoint in that same environment.


Authentication

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.

Required headers

HeaderValuePurposeRequired on
AuthorizationBearer {{accessToken}}Authenticates the user with the serverAll requests
Key{{apiKey}}Authenticates the application with the serverAll requests
Content-Typeapplication/jsonDeclares the request body media typedataIngestion/ingest
Content-Typemultipart/form-data; boundary=<calculated when request is sent>Declares a file upload bodymedia/upload
Acceptapplication/jsonDeclares the acceptable response typeAll 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 lifetimes

CredentialLifetime
Authorization code10 minutes
API keyNo expiry
Access token30 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 Authorization or Key header values. Every credential on this page is a placeholder.


Upload a file

Use Media Upload API V3 to upload the source file.

POST /api/v3/media/upload

The 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.

Query parameters

ParameterRequiredTypeDescription
assetTypeYesStringThe type of asset being uploaded, for example file, image, or video
fileNameYesStringThe name of the file to upload, including its extension — for example customers.xlsx

Form-data body

FieldRequiredDescription
fileYesSource of the uploaded media content

Example request

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.

Example response

{
  "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.

Media Upload response fields

FieldTypeDescription
idStringUnique identifier for the uploaded content
mimeTypeStringThe asset type and format, for example image/png
nameStringThe file name
urlURLThe URL of the uploaded content on the Sprinklr platform
previewUrlURLThe preview URL of the uploaded content
sizeIntegerThe size of the uploaded content in bytes
widthIntegerWidth of the uploaded content. Returned for image and video asset types
heightIntegerHeight of the uploaded content. Returned for image and video asset types
previewWidthIntegerPreview width. Returned for the image asset type
previewHeightIntegerPreview 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/upload once per file rather than using the V2 /media/upload/multiple path.


Submit a data ingestion task

After uploading the source file, submit the ingestion task:

POST /api/v3/dataIngestion/ingest

The path segment is dataIngestion — camelCase, not data-ingestion. This is the change most likely to break a V2 integration. See Migrating from V2.

Request parameters

FieldTypeRequiredDescription
typeStringYesType of ingestion — PROFILE, INFLUENCER_PROFILE, or LISTENING_MESSAGE
nameStringYesUnique task name
fileNameStringYesName of the file
fileUrlStringYesURL of the file to load data from — the data.url returned by Media Upload
templateNameStringYesName of the template to use for ingestion, as saved in the UI
callbackUrlStringYesCallback URL to receive notification on completion
importTagStringYesTag for filtering
callbackTypeStringRequired when callbackUrl is providedType of callback to use
callbackUrlHeadersObject (string → string)NoHeaders sent with the callback request, for authenticating the call into your receiver
identifierFieldsObject (string → array of strings)NoYour own unique identifiers, used to match existing data instead of Sprinklr identifiers. PROFILE only
idStringNoTask-related identifier
ingestionTaskIdStringNoExisting ingestion task identifier
statusStringNoIngestion-task status
externalSourceTypeStringNoExternal-source type
credentialsIdStringNoCredentials identifier
additionalObjectNoAdditional task information

Send all eight of the fields marked Required above on every call. fileName and importTag are easy to omit if you are porting a V2 payload — include both.

Example — Import profile

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.

Example — Import messages

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.

Example response

{
  "data": "{\"taskId\":\"6033961866934b5708a5f90a\"}",
  "errors": []
}

data is 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.


Use custom profile identifiers

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.


Handle the response

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.


Handle ingestion completion

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.

Response status codes

HTTP codeScenario
200 OKSuccess. Ingestion returns a taskId; upload returns content metadata
400 Bad RequestMissing required field, unknown type, malformed multipart body, or unreachable fileUrl
401 UnauthorizedInvalid or missing Authorization token or Key header
403 ForbiddenCaller lacks permission to ingest data or upload media
404 Not FoundWrong path — most often data-ingestion instead of dataIngestion. Also an unknown templateName

The error object

FieldTypeDescription
idStringError identifier
codeIntegerNumeric error code
messageStringError key, for example account.not.found

Troubleshooting

SymptomLikely causeFix
404 on every ingestion callUsing data-ingestion (kebab) instead of dataIngestion (camelCase)Change the path. This is the number-one V3 migration failure
400 naming fileNamefileName is required in V3Add fileName
400 naming importTagimportTag is requiredAdd importTag
400 on typeValue not one of PROFILE, INFLUENCER_PROFILE, LISTENING_MESSAGE, or wrong caseUse one of the three exactly
400 on templateNameTemplate does not exist, or the name does not match exactlyRe-check the name saved in the UI
Client fails deserializing dataIngestion returns data as a JSON-encoded string, not an objectParse twice
400 on multipart uploadContent-Type hard-coded without a matching boundaryLet the HTTP client set the header
Upload succeeds, ingestion 400s on fileUrlThe content-store URL is environment-specificUpload and ingest in the same {env}
Callback never arrivesReceiver does not return 200 to an empty POST, or the TLS certificate is invalidVerify both
Callback arrives, results look wrongYou are reading the synchronous response, not the callback payloadPer-record counts are callback-only
Cannot tell which rows failedThe synchronous response has no per-record dataDownload failedFileUrl — the reason is in the last column
401 with all headers presentCredentials belong to a different environmentRegenerate for the target environment
401 after previously workingToken expired (30-day default), or a second token was issued for the same keyRefresh; one key per service
Uploaded file not in Asset ManagerThe content store is not Asset ManagerCall Asset Create separately

Migrate from V2

Update integrations that use the V2 Data Ingestion endpoint to use the V3 path.

- POST /api/v2/data-ingestion/ingest
+ POST /api/v3/dataIngestion/ingest

For 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.

Common Use Cases

Nightly CRM to Sprinklr profile sync

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.

Match on your own customer key

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.

Import historical messages for listening and AI

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.

Reconcile results and retry failures

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 mapping

successfulFileUrl is the only way to map your rows back to Sprinklr IDs.

Handle re-runs safely

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.

Attach images or documents to a workflow

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.


Best practices

Path and namespace

  • The path is dataIngestion, camelCase. data-ingestion returns 404.
  • Keep the base path in one configuration constant.

Request body

  • Send type, name, fileName, fileUrl, templateName, callbackUrl, and importTag on every call.
  • type accepts PROFILE, INFLUENCER_PROFILE, and LISTENING_MESSAGE, and is case-sensitive.
  • Never send an empty fileUrl.

Asynchrony

  • The 200 is an acknowledgement, not a result. Per-record outcomes arrive only at the callback.
  • Your callback receiver must return 200 to an empty POST and present a valid TLS certificate.
  • Always download failedFileUrl when failedRecordsCount > 0; the reason is in the last column.
  • Store the taskId — it is the id on the callback payload and your only correlation handle.

Response parsing

  • Ingestion returns data as a JSON-encoded string. Parse twice.
  • Media Upload returns data as a real object. The two endpoints differ.
  • Always inspect the errors array, not just the HTTP status.
  • startTime and completionTime are epoch milliseconds.

Media upload

  • Let your HTTP client set the multipart Content-Type boundary.
  • The form field name is file.
  • Send fileName with 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.
  • templateName must match exactly.
  • A 403 is 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.