Developers & AI builders

Developers & AI Builders

Everything you need to integrate the Sentient Pipeline and Emotional Call Handling & Profiling API — authentication, endpoints, response objects, and a ready-to-run script. Use of the API is subject to our Emotional API Acceptable Use Policy.

Sentient Machines Public API

Overview

The Sentient Public API turns a call recording into conversation intelligence — a full transcript, plus sentiment, risk flags, vulnerability signals, emotional scores and more — and lets you read that analysis back into your own systems, per call or per customer. Everything below sits under a single /v1 version prefix on your own instance's host, secured by organization-scoped bearer tokens:

  • Submit and track — upload a recording (or send an email or chat conversation as JSON) once, poll it while it runs, then fetch its transcript, tags, risk flags and your own metadata when it completes.
  • Per-call analytics, included — Get result returns that call's emotion and voice-authenticity scores inline, in the same response as the transcript. No second call, no second id to track.
  • Look up a conversation directly — GET /v1/conversations/:id fetches one conversation's own record by id, independent of the job-tracking flow above.
  • Per-customer history — ask for everything you know about one caller by phone number: how many times they've called, how their sentiment is trending, and each call's own scores.
  • Per-agent performance — ask for one agent's own EHRI/AEHS performance and risk profile by name, plus their most recent calls.

One base URL

Every endpoint in this reference is relative to https://api.<your-instance>.sentientmachines.tech, using the host your Sentient Machines contact assigned you — every path below already includes its own /v1 version prefix, so POST /v1/investigate below means exactly POST https://api.<your-instance>.sentientmachines.tech/v1/investigate, nothing more to add. The same bearer token works against all six endpoints; a token is tied to your organization and its scopes, never to one endpoint over another.

Before your first request: get your origin IP allowlisted

A valid bearer token isn't enough on its own — the network your calls come from has to be allowlisted too, or every request is rejected regardless of the token. Send your outbound IP address(es) to your Sentient Machines contact before you start integrating; it's a one-time setup step, done before any of the calls below will work.

Checking you're allowlisted: GET /v1/health

GET /v1/health needs no token and returns { "ok": true }. It's the quickest way to confirm your network can reach the API at all — useful before you have a token, and useful afterwards to tell "my IP isn't allowlisted" apart from "my token is wrong". If this returns 200 but your real calls return 403, the problem is the token or its scopes, not the network.

Authentication & scopes

Every request carries a bearer token in the Authorization header. The token identifies your organization — it's how the API knows your default pipeline configuration (and which ones, if more than one, you're licensed to name explicitly via manifestId, see Submit a job), and which jobs and profiles you're allowed to look up. A token alone won't get a request through, though — see Overview for the IP allowlisting step that has to happen first.

header
Authorization: Bearer YOUR_API_TOKEN

A token is also scoped to what it's allowed to do, granularly — there's no hierarchy, so each capability below has to be requested explicitly. Most integrations that submit calls also want conversations.read — see the callout below for why.

ScopeGrants
pipeline.submit POST /v1/investigate and GET /v1/investigate/:jobId.
conversations.read The transcript from GET /v1/investigate/:jobId/result, and GET /v1/conversations/:id.
emotional-metrics.read The metrics block inside Get result.
customer-profiles.read POST /v1/customer-profile.
agent-profiles.read POST /v1/agent-profile.
credits.read GET /v1/credit-report.

Want analytics with your results? Ask for conversations.read + emotional-metrics.read too

Get result spans two scopes on its own: the transcript needs conversations.read, while the metrics block inside the same response separately needs emotional-metrics.read. A token with conversations.read but not emotional-metrics.read still gets a normal 200 with the full transcript — but metrics comes back null rather than erroring. If you're seeing "metrics": null on every call, check your token's scopes before looking anywhere else.

Keep it secret

Treat your token like a password. If it's ever exposed, ask your contact to rotate it — there's no self-service reset yet.

Quickstart

The full round trip, start to finish.

1

Submit the recording

POST /v1/investigate with the audio file. You get back a jobId immediately — the job itself runs in the background.

2

Poll until it's done

GET /v1/investigate/:jobId on whatever interval suits you. Watch status move from running to complete.

3

Read the result

GET /v1/investigate/:jobId/result once it's complete, for the transcript, tags, risk flags, your metadata, and that call's metrics — all in one response.

4

Look up the caller's history, any time after

POST /v1/customer-profile for everything recorded under a phone number so far — call count, sentiment trend, and each call's own scores.

5

Or look up an agent's own profile

POST /v1/agent-profile for one agent's EHRI/AEHS performance and risk profile, plus their most recent calls.

6

Or fetch a conversation directly by id

GET /v1/conversations/:id if you already have the conversation's own id and don't need the job-tracking flow above.


POST Submit a job

Upload a call recording, or submit an email or chat conversation, for analysis. Returns right away with a job id — processing continues asynchronously.

POST /v1/investigate 🔒 pipeline.submit

Request body — multipart/form-data (call recording)

FieldTypeRequiredDescription
file file Required The audio recording to analyze.
creationDate ISO 8601 Optional When the interaction actually happened, if different from now. Defaults to the time of submission.
  • 2026-08-28T14:32:00Z
  • 2026-08-28T09:32:00-05:00
meta.<key> string Optional Any number of your own key/value pairs (e.g. meta.accountRegion). Echoed back unchanged in the result, so you can correlate it with your own records. Keys starting o__ are reserved for structured use — see the callout below.
manifestId string Optional Which of your organization's licensed pipeline configurations to run this job through. Omit it to use your organization's default — most integrations never need to set this.
  • default
  • marketing-calls

Reserved meta.o__* keys

These meta. keys are recognized specially and stored as structured fields instead of opaque metadata. Names are case-sensitive, and each is optional:

  • meta.o__direction — call direction, in or out.
  • meta.o__from_number — the calling party's phone number.
  • meta.o__to_number — the called party's phone number.
  • meta.o__customer_ref — your own reference for the customer (an account number or email address, say). Customer profile can look the customer up by this value with customerRef. Matching ignores surrounding spaces, and ignores case if the value contains an @. On email and chat conversations you send customerRef at the top level of the body instead, and a meta.o__customer_ref there is rejected (400).
  • meta.o__agentName — the handling agent's name. This is the value Agent profile looks up, by exact (case-sensitive) match, so send it spelled the same way every time. A call submitted without it can't be found by agent name.

Customer profile matches on o__from_number for an in call and o__to_number for an out call, or on o__customer_ref. A call with none of these, or with a number but no o__direction, doesn't appear in any customer's profile.

Anything starting meta.o__c_ or meta.o__t_ is reserved for the service itself and shouldn't be sent. Any other meta.<key> is stored as-is and simply echoed back in Get result — it isn't otherwise interpreted.

Emails and chats

To submit an email or chat conversation instead of a recording, send an application/json body to the same endpoint — see Email and chat conversations below. The rest of this section (authentication, manifestId, status and result) applies to both.

Need a specific pipeline?

Most integrations never set manifestId — your organization already has a default pipeline configured. If you run more than one kind of analysis (a different configuration per campaign or business line, say), ask your Sentient Machines contact to license your organization for the extra manifest name(s) first; naming one you're not licensed for is rejected with 403.

Request

curl
curl -X POST https://api.your-instance.sentientmachines.tech/v1/investigate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@call-recording.wav" \
  -F "meta.o__customer_ref=ACC-4471" \
  -F "meta.o__agentName=Alex Rivera"

Response — 201 Created

json
{
  "jobId": "e424667a-c3fc-4563-9e2d-4be7db6743f4",
  "organization": "acme-corp"
}

Email and chat conversations — request body, application/json

FieldTypeRequiredDescription
type string Required email or chat.
conversationTurns array Required The messages, 1 to 500 of them, in any order (they are sorted by timestamp). See the turn fields below.
conversationId string Optional Your own identifier for the conversation. Strongly recommended: it is how a later submission of the same conversation is recognised — see Sending a conversation again.
customerRef string | string[] Optional Who the customer is, in your own terms (an email address or account id). If omitted, the from.address of the first customer turn is used; if there is none, the request is rejected (422). Email-shaped values are trimmed and lowercased.
participants array Optional { "address", "role" } entries, where role is customer, agent or bot. Used to work out who sent each turn.
subject string Optional The email subject or chat topic. Stored with the conversation.
creationDate ISO 8601 Optional When the conversation happened, if different from now. Defaults to the time of submission.
handlingTimeSecs integer Optional How long the conversation took to handle, in seconds (a positive integer). If omitted it is worked out from the turn timestamps.
meta object Optional Your own flat string-to-string key/value pairs, echoed back in the result. o__direction (in/out; required when the first turn is a bot (400 without it), because turn order cannot tell a bot's greeting from a bot's outreach; otherwise it defaults to in when the customer wrote first and out when an agent did) and o__agentName (the agent's name, as for Agent profile; for an email it defaults to the first agent turn's from.name, else its address) are understood; o__customer_ref and keys starting o__c_ are reserved and rejected (400). See Reserved meta.o__* keys.
manifestId string Optional As for recordings: which licensed pipeline to run. Omit it to use your organization's default. It must have an entry point for the conversation's type, or the request is rejected (422).

Each item of conversationTurns

FieldTypeRequiredDescription
text string Required The message body. May be HTML. Stored exactly as sent.
timestamp ISO 8601 Required When the message was sent.
speaker string Optional customer, agent or bot. If omitted it is worked out — see below.
plainText string Optional A plain-text rendering of text. Must not contain HTML.
from object Optional { "address", "name" }, both optional.
email object Optional { "messageId", "to", "cc", "bcc" } (the last three are arrays of addresses). Email conversations only.
meta object Optional Your own flat string-to-string pairs for this turn. Keys starting o__t_ are reserved and rejected (400).

How a turn's speaker is chosen

  • The turn's own speaker, if you send one.
  • Otherwise the role of the participants entry whose address matches the turn's from.address (ignoring case).
  • Otherwise agent, if from.address is present and participants is not empty.
  • Otherwise the request is rejected (400), naming the turn.

What is analysed: HTML and plain text

Your text is stored unchanged, but the analysis reads plain text. That is your plainText if you send one; otherwise text as it is when it contains no HTML; otherwise text with the HTML removed (paragraphs, line breaks and list items become lines; link text is kept and link addresses are dropped). Plain text that merely contains angle brackets, such as Jane <jane@example.com>, is not treated as HTML. A turn with no text left after this is rejected.

Sending a conversation again

Each conversation has a key: your conversationId, scoped to your organization. Without one the key is derived from the earliest turn (its type, exact timestamp, sender and recipients), so the earliest turn must be resent unchanged. Send a conversationId and you avoid this. When a submission arrives for a conversation you already sent:

  • Identical turns (same messages, same content) — 200 with "duplicate": true and the existing jobId. Nothing new runs and no credits are used.
  • Turns added, removed or edited, and the earlier job has finished — the conversation is analysed again with the new turns: 201 with "supersedes" naming the earlier job.
  • Changed turns while the earlier job is still running — 409 with inFlightJobId. Send it again once that job is complete.

Credits

A conversation is charged by its length: 50 credits for up to the first 500 characters of analysed text, then 50 more for each further 500, pro-rata (750 characters costs 75).

Example request — an email conversationclick to expand
curl
curl -X POST https://api.your-instance.sentientmachines.tech/v1/investigate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "email",
  "conversationId": "ticket-8812",
  "subject": "Router order not received",
  "participants": [
    {
      "address": "jane@example.com",
      "role": "customer"
    },
    {
      "address": "alex@acme-corp.com",
      "role": "agent"
    }
  ],
  "meta": {
    "o__agentName": "Alex Rivera"
  },
  "conversationTurns": [
    {
      "text": "<p>Hello, my router order is three weeks late and nobody has replied to my emails.</p>",
      "timestamp": "2026-10-01T09:00:00Z",
      "from": {
        "address": "jane@example.com",
        "name": "Jane"
      },
      "email": {
        "messageId": "<m1@example.com>",
        "to": ["support@acme-corp.com"]
      }
    },
    {
      "text": "<p>Hi Jane, I'm sorry about that. It ships today and should reach you tomorrow.</p>",
      "timestamp": "2026-10-01T09:20:00Z",
      "from": {
        "address": "alex@acme-corp.com",
        "name": "Alex"
      },
      "email": {
        "messageId": "<m2@example.com>",
        "to": ["jane@example.com"]
      }
    }
  ]
}'

Response — 201 Created

json
{
  "jobId": "e424667a-c3fc-4563-9e2d-4be7db6743f4",
  "organization": "acme-corp"
}

The same conversation sent again — 200 OK

json
{
  "jobId": "e424667a-c3fc-4563-9e2d-4be7db6743f4",
  "organization": "acme-corp",
  "duplicate": true
}

A longer version, once the first job finished — 201 Created

json
{
  "jobId": "5b1f9c52-71a0-4d0e-8c3a-0f6f2f8f1d21",
  "organization": "acme-corp",
  "supersedes": "e424667a-c3fc-4563-9e2d-4be7db6743f4"
}

Responses

201Accepted. Save the jobId — you'll need it for both calls below. For a resent conversation the body also carries "supersedes", the job it replaces.
400No file part found, the file isn't a recognized audio type (wav, mp3, m4a, aac, ogg, flac, webm), or it has a recognized extension but can't be decoded as audio (corrupt, truncated, or not the format its extension claims). Don't retry a file that fails this way; fix or replace it. For an email/chat JSON body: malformed JSON or a wrong field type; type not email/chat; no, too many or malformed turns; a missing or invalid text/timestamp; an unknown speaker; plainText containing HTML; a turn with no text left; a speaker that cannot be worked out; a reserved meta key; or no conversationId when the earliest turn has no from.address. The message names the first problem.
401Missing or invalid bearer token.
403Your token doesn't have the pipeline.submit scope, or you named a manifestId your organization isn't licensed for. (A normal JSON error — not the network-level IP-allowlist 403 described under Errors.)
422Your organization isn't licensed for any pipeline manifest yet — contact your Sentient Machines representative. Also returned for an email/chat conversation when customerRef cannot be determined (send it, or include a customer turn with from.address), or when your pipeline has no entry point for the conversation's type.
500The upload or pipeline lookup failed unexpectedly. Safe to retry.
200Email/chat only: you already sent exactly this conversation. { "jobId", "organization", "duplicate": true } — the existing job; nothing new runs.
402Your organization has no job credits available.
409Email/chat only: you changed the type of an existing conversation, or an earlier version of it is still being processed (inFlightJobId). Retry once that job is complete.
413Email/chat only: the JSON body is over the size limit (2 MB by default).
429Your organization already has its maximum number of jobs in flight. Retry shortly.

GET Check status

Look up where a job currently stands in the pipeline. Cheap enough to poll on a short interval.

GET /v1/investigate/:jobId 🔒 pipeline.submit

Path parameter

FieldTypeDescription
jobId string The id returned when you submitted the job.

Request

curl
curl https://api.your-instance.sentientmachines.tech/v1/investigate/e424667a-c3fc-4563-9e2d-4be7db6743f4 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response — 200 OK

json
{
  "jobId": "e424667a-c3fc-4563-9e2d-4be7db6743f4",
  "status": "RUNNING",
  "currentStageId": "sentiment_classifier",
  "startedAt": "2026-08-28T11:46:10.735Z",
  "updatedAt": "2026-08-28T11:46:24.108Z",
  "completedAt": null
}

Responses

200Current status, shown below.
401Missing or invalid bearer token.
404No job with that id, or it belongs to a different organization — the two are indistinguishable on purpose.

GET Get result

Read back what the pipeline produced. Call this once status reads complete.

GET /v1/investigate/:jobId/result 🔒 conversations.read

Path parameter

FieldTypeDescription
jobId string The id returned when you submitted the job.

Request

curl
curl https://api.your-instance.sentientmachines.tech/v1/investigate/e424667a-c3fc-4563-9e2d-4be7db6743f4/result \
  -H "Authorization: Bearer YOUR_API_TOKEN"
Example response — 200 OKclick to expand
json
{
  "jobId": "e424667a-c3fc-4563-9e2d-4be7db6743f4",
  "id": "6a9175051d000031000fcb4f",
  "creationDate": "2026-08-28T11:46:10.735Z",
  "tags": {
    "sentiment": "neutral",
    "customerSentiment": "neutral",
    "vulnerability": "nonVulnerable",
    "contactChannel": "Calls"
  },
  "risks": [
    { "text": "c-Gratitude-b" }
  ],
  "metadata": {
    "o__customer_ref": "ACC-4471"
  },
  "utterances": [
    {
      "startTime": 0,
      "endTime": 3.28,
      "speaker": "agent",
      "text": "Thank you for calling, how can I help?",
      "findings": []
    },
    {
      "startTime": 3.64,
      "endTime": 6.64,
      "speaker": "customer",
      "text": "Hi, this is Alex, I have a question about my account.",
      "findings": [
        { "classifier": "pii_classifier_v2.5", "label": "PERSON", "confidence": 1 },
        { "classifier": "audio_text_sentiment", "label": "a-frustration", "confidence": 0.42 }
      ]
    }
  ],
  "analysis": {
    "aiSummary": "Agent: greeted the caller and offered help.\nCustomer: asked about a charge on their account."
  },
  "metrics": {
    "speechFileId": "6a9175051d000031000fcb4f",
    "day": "2026-08-28",
    "emotion": {
      "f": 0.5,
      "a": 0,
      "c": 0.5,
      "eri": 66.67,
      "sentimentScore": 0.06,
      "deltaSentiment": "neutral_to_neutral"
    },
    "deepfake": {
      "ali": 0.485,
      "scf": 1,
      "sra": 0.0973,
      "speakerConfMean": -1,
      "silenceRatio": 0.2027,
      "vulnerabilityLabel": "v-non-vulnerable"
    }
  }
}

Body

FieldTypeDescription
jobIdstringThe same id you submitted and polled with.
idstringInternal record id for this interaction. Stable, and safe to store as your own foreign key for this call.
creationDateISO 8601When the interaction happened (from submission, or when it was recorded).
tagsobjectKey/value classification output — sentiment, vulnerability, and more, depending on your pipeline configuration.
risksarrayNotable moments the pipeline flagged, each as { "text": "…" }. Empty when nothing was flagged.
metadataobjectWhatever meta.<key> fields you attached at submission, unchanged.
utterancesarrayThe call transcript, broken into speaker turns, in chronological order. See Utterance object below.
analysisobjectPipeline-generated narrative output. Currently just aiSummary — a short plain-language recap of the call, or null if your pipeline configuration doesn't include the summarization stage.
metricsobject | nullThis call's emotion and voice-authenticity scores. See Metrics object for every field. null if your token lacks the emotional-metrics.read scope, or if the scores couldn't be produced for this call — the transcript above is unaffected either way.

Utterance object

FieldTypeDescription
startTimenumberSeconds from the start of the recording to the start of this turn.
endTimenumberSeconds from the start of the recording to the end of this turn.
speakerstringWho said it — e.g. agent, customer, or bot, depending on your pipeline's speaker model. "unknown" if it couldn't be resolved for this turn.
textstringWhat was said during this turn.
findings array Everything the pipeline flagged within this turn (PII, vulnerability, sentiment, and other classifier hits), each as { "classifier": "…", "label": "…", "confidence": 0.0–1.0 }. Doesn't include speaker classification — that's already broken out as speaker above. Empty when nothing was flagged in this turn.

Analytics arrive with the transcript

The metrics block is assembled for you as part of this response — you don't need a second request, and you don't need to hold onto a separate id to fetch it. Scores are normally ready by the time a job reads complete; if they aren't, the first request computes them on demand rather than making you wait for the next cycle, so no extra delay is needed on your side.

Results for emails and chats

The result has the same shape. utterances are the conversation's sentences in order, each with the speaker (customer, agent or bot) and the same findings. Their startTime/endTime are positions within the text (one word per second), not real time. metrics is null: the voice-based emotion scores only exist for recordings. Your meta comes back in metadata, together with the service-set o__direction, o__customer_ref, o__c_subject and o__c_contentHash.

Responses

200Result, shown above. metrics may be null, or carry null fields within it — see Metrics object.
401Missing or invalid bearer token.
403Your token doesn't have the conversations.read scope.
404No job with that id, it isn't yours, or it hasn't reached complete yet.

GET Conversation

Fetch one conversation's own record directly by id, independent of the job-tracking flow above — useful when you already have the id from somewhere other than a fresh submission.

GET /v1/conversations/:id 🔒 conversations.read

Path parameter

FieldTypeDescription
id string The conversation's own id — the same field Get result returns, and the same one Metrics object is keyed by.

Query parameter

FieldTypeRequiredDescription
includeEmotionalMetrics boolean Optional Set to true to also attach this call's emotion/voice-authenticity scores under metrics, same data as Get result's own metrics block. Omit it (or anything other than exactly true) and no second call is made at all — metrics isn't just null, it's absent from the response entirely.

Metrics are opt-in here — and unlike Get result, denial is reported

Without ?includeEmotionalMetrics=true, this endpoint never calls out for metrics at all, so there's nothing to fail and nothing to report. Ask for it explicitly and your token has emotional-metrics.read? You get metrics populated. Ask for it and DON'T have the scope (or it's genuinely unavailable)? You get metrics: null plus a metricsError explaining why — see the Body table below. That's the opposite of Get result, which always attempts metrics silently and never explains a null — the difference is that here you had to ask, so a plain "no" isn't good enough on its own.

Request — with metrics

curl
curl "https://api.your-instance.sentientmachines.tech/v1/conversations/6a9175051d000031000fcb4f?includeEmotionalMetrics=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
Example response — 200 OK, with metricsclick to expand
json
{
  "id": "6a9175051d000031000fcb4f",
  "creationDate": "2026-08-28T11:46:10.735Z",
  "tags": {
    "sentiment": "neutral",
    "customerSentiment": "neutral",
    "vulnerability": "nonVulnerable",
    "contactChannel": "Calls"
  },
  "risks": [
    { "text": "c-Gratitude-b" }
  ],
  "metadata": {
    "o__customer_ref": "ACC-4471"
  },
  "utterances": [
    {
      "startTime": 0,
      "endTime": 3.28,
      "speaker": "agent",
      "text": "Thank you for calling, how can I help?",
      "findings": []
    }
  ],
  "analysis": {
    "aiSummary": "Agent: greeted the caller and offered help.\nCustomer: asked about a charge on their account."
  },
  "metrics": {
    "speechFileId": "6a9175051d000031000fcb4f",
    "day": "2026-08-28",
    "emotion": { "f": 0.5, "a": 0, "c": 0.5, "eri": 66.67, "sentimentScore": 0.06, "deltaSentiment": "neutral_to_neutral" },
    "deepfake": { "ali": 0.485, "scf": 1, "sra": 0.0973, "speakerConfMean": -1, "silenceRatio": 0.2027, "vulnerabilityLabel": "v-non-vulnerable" }
  }
}

Response when requested but not permitted

Same request, but the token lacks emotional-metrics.read — still 200, everything else unchanged, only the tail of the response differs:

json
  ...
  "metrics": null,
  "metricsError": {
    "code": "insufficient_scope",
    "message": "Token does not have the 'emotional-metrics.read' scope."
  }
}

Body

FieldTypeDescription
idstringSame value as the id you requested — echoed back so this payload is self-describing.
creationDateISO 8601When the interaction happened.
tagsobjectKey/value classification output, same shape as Get result's.
risksarrayNotable moments the pipeline flagged. Empty when nothing was flagged.
metadataobjectWhatever meta.<key> fields were attached at submission, unchanged.
utterancesarrayThe call transcript, same shape as Utterance object.
analysisobjectSame shape as Get result's — currently just aiSummary.
metricsobject | null | absentAbsent entirely unless you passed ?includeEmotionalMetrics=true. When you did: this call's emotion/voice-authenticity scores (see Metrics object), or null if unavailable — check metricsError.
metricsErrorobject | absentOnly present when metrics was requested and came back null. { "code", "message" }, where code is "insufficient_scope" (missing the scope), "not_found" (no metrics exist for this call), or "unavailable" (transient failure; safe to retry).

Responses

200Conversation, shown above.
401Missing or invalid bearer token.
403Your token doesn't have the conversations.read scope.
404No conversation with that id, or it isn't yours — deliberately indistinguishable, same non-enumeration convention as Check status.

POST Customer profile

A customer's whole emotional-history profile across every call, email and chat so far, looked up by phone number(s) and/or your own customer reference(s).

POST /v1/customer-profile 🔒 customer-profiles.read

Request body — application/json

FieldTypeRequiredDescription
phone string | string[] At least one of phone / customerRef The customer's number. Normalized to E.164 against your instance's configured default region before lookup, so a local-format number from that region (07700 900123) and its international form (+447700900123) resolve to the same customer. Never stored raw: only a one-way hash of it is ever kept. Matched against whatever you submitted as meta.o__from_number / meta.o__to_number at submission (same normalization applied to both sides).
customerRef string At least one of phone / customerRef Your own reference for the customer, exactly as you sent it as meta.o__customer_ref at submission. Surrounding spaces are ignored, and so is case if the value contains an @ (an email address). Returns the profile across every call, email and chat that carried this reference, even if the calls came from different phone numbers.
conversationType string Optional "call", "email" or "chat": build the profile from that type only. Omitted, the profile covers every type. Mixing calls and text blends different signals, so use this when you want a like-for-like baseline; conversationTypes in the response says what contributed.
limit number Optional How many of the most recent calls to return in callSeries. Defaults to your instance's configured window (5 unless your contact has changed it), which is also the ceiling — asking for more than that returns the maximum rather than erroring. Note this only trims callSeries; calls and the baseline/trend figures are always computed across the customer's whole history.

Several values name one customer

phone and customerRef each take one value or a list, and may be sent together (up to 20 values in all). Every value names the same customer, and the profile merges the calls, emails and chats known by any of them, in date order. We don't check that you're right: send values for different people and you get a blended profile. A person who phones and emails is two customers to us unless you send both identifiers in one request. Blank values are ignored; a request with no value at all is rejected with 400. Values we hold nothing for are listed in missing.

Numbers from outside your default region

Normalization uses one configured default region per instance, so a number written in another country's local format won't match. If your callers span multiple countries, send meta.o__from_number / meta.o__to_number in full international +-prefixed form at submission and look them up the same way — that form is unambiguous regardless of which region your instance is configured for.

Why it's a POST

A phone number is sensitive — putting it in a URL would leak it into access logs and proxy logs by default. Sending it in the request body instead keeps it out of anything that logs the request line.

Request

curl
curl -X POST https://api.your-instance.sentientmachines.tech/v1/customer-profile \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+447700900123", "limit": 3}'

Request — by customerRef

curl
curl -X POST https://api.your-instance.sentientmachines.tech/v1/customer-profile \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customerRef": "ACC-4471", "limit": 3}'

Request — one customer known by a phone number and an email address

curl
curl -X POST https://api.your-instance.sentientmachines.tech/v1/customer-profile \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+447700900123", "customerRef": ["jane@example.com", "ACC-4471"]}'
Example response — 200 OKclick to expand
json
{
  "customerId": "CUST-4020C31C-CCC2AA3CD3",
  "calls": 3,
  "firstCall": "2026-08-19",
  "lastCall": "2026-09-16",
  "departments": ["Collections", "Retail Banking"],
  "meanSentiment": -0.18,
  "trend": "Deteriorating",
  "baselineFac": { "f": 0.14, "a": 0.07, "c": 0.79 },
  "latestFac": { "f": 0.61, "a": 0.22, "c": 0.17 },
  "deviation": { "f": 0.47, "a": 0.15, "c": -0.62 },
  "deviationFlagged": true,
  "vulnerabilityFlags": [
    { "date": "2026-09-16T09:12:44+00:00", "label": "vulnerable" }
  ],
  "callSeries": [
    {
      "date": "2026-08-19T14:02:11+00:00",
      "sentimentScore": 0.12,
      "eri": 33.43,
      "f": 0.14,
      "a": 0.07,
      "c": 0.79,
      "dri": null,
      "riskBand": null,
      "agentName": "Alex Rivera",
      "department": "Retail Banking",
      "vulnerability": "nonVulnerable",
      "deltaSentiment": "neutral_to_positive",
      "businessIssues": "nonBi",
      "behaviour": [
        { "dimension": "empathy", "value": 0.82 },
        { "dimension": "listening", "value": 0.74 },
        { "dimension": "proactive", "value": 0.61 },
        { "dimension": "respect", "value": 0.9 },
        { "dimension": "friendly", "value": 0.88 },
        { "dimension": "compassion", "value": 0.7 }
      ],
      "aiSummary": "Agent: welcomed the caller and confirmed their account details.\nCustomer: asked about opening a savings account.\nKey points: no issues raised, straightforward product enquiry.\nConclusion: agent talked through savings options; customer said they'd think it over."
    },
    {
      "date": "2026-09-02T10:47:38+00:00",
      "sentimentScore": -0.21,
      "eri": 65.36,
      "f": 0.33,
      "a": 0.17,
      "c": 0.5,
      "dri": 38.4,
      "riskBand": "Low",
      "agentName": "Priya Nair",
      "department": "Collections",
      "vulnerability": "nonVulnerable",
      "deltaSentiment": "neutral_to_negative",
      "businessIssues": "bi",
      "behaviour": [
        { "dimension": "empathy", "value": 0.55 },
        { "dimension": "listening", "value": 0.48 },
        { "dimension": "proactive", "value": 0.4 },
        { "dimension": "respect", "value": 0.63 },
        { "dimension": "friendly", "value": 0.5 },
        { "dimension": "compassion", "value": 0.44 }
      ],
      "aiSummary": "Agent: explained the missed-payment notice and offered a revised plan.\nCustomer: pushed back on the fee, citing a billing error from last month.\nKey points: disputed fee not yet resolved; customer asked for a callback from a supervisor.\nConclusion: agent logged a dispute ticket and promised a callback within 48 hours."
    },
    {
      "date": "2026-09-16T09:12:44+00:00",
      "sentimentScore": -0.45,
      "eri": 90.32,
      "f": 0.61,
      "a": 0.22,
      "c": 0.17,
      "dri": 72.6,
      "riskBand": "High",
      "agentName": "Priya Nair",
      "department": "Collections",
      "vulnerability": "vulnerable",
      "deltaSentiment": "negative_to_negative",
      "businessIssues": "bi",
      "behaviour": [
        { "dimension": "empathy", "value": 0.3 },
        { "dimension": "listening", "value": 0.35 },
        { "dimension": "proactive", "value": 0.28 },
        { "dimension": "respect", "value": 0.52 },
        { "dimension": "friendly", "value": 0.31 },
        { "dimension": "compassion", "value": 0.22 }
      ],
      "aiSummary": "Agent: reiterated the outstanding balance and threatened escalation.\nCustomer: became distressed, said they were struggling financially and felt pressured.\nKey points: customer expressed financial hardship; vulnerability signals raised during the call.\nConclusion: call flagged for vulnerability review; agent did not offer a hardship plan."
    }
  ]
}

Body

FieldTypeDescription
customerIdstringA stable, non-reversible id for this customer — the raw number is never derivable from it. Safe to store and use as your own key for this caller. Present when the request named one value; omitted when it named several, since a merged profile has no single id.
conversationTypesarrayWhich types the profile is built from, sorted: any of "call", "chat", "email".
missingobject{ "phone": [], "customerRef": [] }: the values from your request that no conversation is known by, as you sent them. A profile is still returned if at least one value matched.
callsnumberHow many conversations (calls, emails and chats) this profile is built from — always the full history, regardless of limit.
firstCall / lastCallstringDates (YYYY-MM-DD) of the oldest and newest call on record for this customer.
departmentsarrayEvery department that has handled this customer, sorted and de-duplicated. ["unknown"] when your pipeline doesn't populate a department.
meanSentimentnumber | nullMean sentiment score across their calls, roughly −1 (negative) to +1 (positive). null if no call has a classified sentiment yet.
trendstring | null"Stable", "Volatile", "Deteriorating", or "Improving" — null until there are at least two calls to compare.
baselineFac / latestFacobjectFrustration/Anxiety/Calm proportions — the customer's early baseline vs. their most recent call(s). Any of f/a/c can be null when a call didn't yield an emotion reading (see Metrics object). On a customer's very first call, baselineFac and latestFac are identical.
deviationobjectHow far latestFac has moved from baselineFac, per dimension. Positive f means more frustrated than usual for this caller.
deviationFlaggedbooleantrue when frustration or anxiety has moved far enough from this customer's own baseline to be worth attention — the useful "is this call unusual for them" signal, rather than an absolute threshold.
vulnerabilityFlagsarrayOne entry per call classified as vulnerable, each as { "date": "…", "label": "vulnerable" }. Empty when none.
callSeriesarrayOne entry per call, oldest first, trimmed to limit. Each carries that call's own scores alongside dri (deepfake risk index, 0–100) and riskBand — both null on every email and chat, and on a caller's first observed call, where there's no prior history to compare a voice against yet — plus a type (call, email or chat), behaviour and aiSummary, described below.

callSeries item — behaviour / aiSummary

FieldTypeDescription
behaviour array | null Six agent soft-skill scores for this call, each { "dimension": "…", "value": 0.0–1.0 }, always in the same order: empathy, listening, proactive, respect, friendly, compassion. null if the call's record is no longer available.
aiSummary string | null A short plain-language recap of the call. null if your pipeline configuration doesn't include the summarization stage, or the call's record is no longer available.

Responses

200Profile, shown above. Always at least one call — a customer with no history is a 404, not an empty profile.
400Neither phone nor customerRef was sent, a value isn't a string or a list of strings, more than 20 values were sent, or conversationType isn't call, email or chat.
401Missing or invalid bearer token.
403Your token doesn't have the customer-profiles.read scope.
404No profile for that number, customerRef or set of values yet (none of them matched, or none matched the conversationType you asked for) — either nothing has been submitted for it, or it doesn't match (see the callout above on normalization).

POST Agent profile

One agent's own EHRI/AEHS performance and risk profile, looked up by agent name, plus their most recent calls.

POST /v1/agent-profile 🔒 agent-profiles.read

Request body — application/json

FieldTypeRequiredDescription
agentName string Required Exact, case-sensitive match against the meta.o__agentName value sent at submission. There's no separate agent directory this is checked against — a typo, or a name that's since changed, simply returns no profile rather than an error.
limit number Optional How many of the agent's most recent calls to return in recentCalls. Defaults to your instance's configured window (5 unless your contact has changed it), which is also the ceiling — asking for more than that returns the maximum rather than erroring.

Why it's a POST

Same convention as Customer profile above: an agent name isn't sensitive in the same direct sense a customer's phone number is, but it's still an identifier tied to individual performance and risk data once this response is attached to it, so it's kept out of URLs and access logs on the same basis.

No per-organization isolation on this endpoint

Unlike Customer profile, an agent name isn't hashed together with your organization the way a phone number is — there's no cryptographic separation between organizations for this lookup. Ask your Sentient Machines contact if that matters for your deployment.

Request

curl
curl -X POST https://api.your-instance.sentientmachines.tech/v1/agent-profile \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agentName": "Alex Rivera", "limit": 2}'
Example response — 200 OKclick to expand
json
{
  "agentName": "Alex Rivera",
  "calls": 214,
  "firstCall": "2026-06-02",
  "lastCall": "2026-09-16",
  "ehriIndex": 108.4,
  "aehsIndex": 106.1,
  "nsir": 0.041,
  "status": "On Track",
  "reliable": true,
  "meanEmpathy": 0.62,
  "meanAgentSentiment": 0.18,
  "meanRiskIndex": 31.2,
  "vulnerable": 6,
  "businessIssueCalls": 19,
  "monthlyTrend": [
    { "month": "2026-08", "meanAehs": 104.9, "calls": 98 },
    { "month": "2026-09", "meanAehs": 106.1, "calls": 62 }
  ],
  "regionMix": [
    { "label": "Retail Banking", "count": 140 },
    { "label": "Card Services", "count": 74 }
  ],
  "recentCalls": [
    {
      "id": "fcb4f",
      "fullId": "6a9175051d000031000fcb4f",
      "date": "2026-09-16",
      "hour": "17:29",
      "durationSecs": 312,
      "sentiment": "positive",
      "deltaKind": "recovered",
      "category": "Card Services",
      "summary": "Customer disputed a card charge; resolved with a refund.",
      "topics": [{ "label": "billing dispute", "confidence": 0.91 }],
      "behaviour": [{ "dimension": "empathy", "value": 0.71 }],
      "airtime": { "agentSecs": 180, "customerSecs": 120, "silencePct": 4 },
      "aehsCall": 109.2
    },
    {
      "id": "1a02b",
      "fullId": "6a9174e91d000031000f1a02b",
      "date": "2026-09-15",
      "hour": "11:04",
      "durationSecs": 201,
      "sentiment": "neutral",
      "deltaKind": "flat",
      "category": "Retail Banking",
      "summary": "Routine balance enquiry.",
      "topics": [],
      "behaviour": [{ "dimension": "empathy", "value": 0.58 }],
      "airtime": { "agentSecs": 95, "customerSecs": 90, "silencePct": 8 },
      "aehsCall": 101.5
    }
  ]
}

Body

FieldTypeDescription
callsnumberHow many calls this profile is built from — always the full history, regardless of limit.
firstCall / lastCallstring | nullDates (YYYY-MM-DD) of the oldest and newest call on record for this agent.
ehriIndex / aehsIndexnumberThis agent's EHRI/AEHS indices, scored against your organization's other agents — 100 is the cohort mean, not a fixed absolute scale.
nsirnumberNet sentiment improvement rate across this agent's calls — roughly −1 (mostly ends worse than it started) to +1 (mostly ends better).
statusstring"Top Tier", "On Track", "Development Priority", or "Low Volume" (too few calls to read reliably — see reliable).
reliablebooleanfalse when this agent's call volume is too low for status/ehriIndex to mean much — they're excluded from the team-level averages other agents are compared against.
vulnerable / businessIssueCallsnumberHow many of this agent's calls were flagged vulnerable, or involved a business issue, respectively.
monthlyTrendarrayThis agent's mean AEHS and call volume per calendar month (YYYY-MM), oldest first.
regionMixarrayThis agent's call volume by department, highest first.
recentCallsarrayTheir limit most recent calls, most recent first — see the item shape below.

recentCalls item

FieldTypeDescription
id / fullIdstringid is a short display id (last 6 characters); fullId is the conversation id used elsewhere in this reference — pass it to GET /v1/conversations/:id.
date / hourstringYYYY-MM-DD and HH:MM, in the instance's own timezone.
deltaKindstring"recovered", "lost", or "flat" — how this call's sentiment moved from start to end.
topicsarrayDetected discussion topics, each { "label": "…", "confidence": 0.0–1.0 }. Empty when none were detected.
behaviourarrayThis call's own agent soft-skill scores, same shape as Customer profile's behaviour.
airtimeobject{ "agentSecs", "customerSecs", "silencePct" } — how the call's talk time split.
aehsCallnumber | nullThis one call's own AEHS score. null if the call has neither an empathy nor a sentiment reading.

Responses

200Profile, shown above. Always at least one call — an agent name with no matching calls is a 404, not an empty profile.
400agentName is missing or blank.
401Missing or invalid bearer token.
403Your token doesn't have the agent-profiles.read scope.
404No calls found tagged with that exact agent name (see the request-field note above on exact matching).

GET Credit report

Your organization's credit balance, the grants that make it up, and what was spent in a period.

GET /v1/credit-report 🔒 credits.read

Query parameters

FieldTypeRequiredDescription
from string Optional First day of the spend period, YYYY-MM-DD (inclusive). Defaults to the first day of the current month.
to string Optional Last day of the spend period, YYYY-MM-DD (inclusive). Defaults to the end of the current month.
tz string Optional An IANA time zone (for example Europe/London) that the dates above are read in. Defaults to your instance's reporting time zone.

Always your own organization

The report is for the organization your token belongs to — there's no way to ask for another one. Only from, to and tz change what you get, and they only affect spend: balance and grants are always as they stand right now. Calling this endpoint is free; it doesn't spend credits.

Request

curl
curl "https://api.your-instance.sentientmachines.tech/v1/credit-report?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
Example response — 200 OKclick to expand
json
{
  "orgId": "your-organization",
  "balance": { "available": 1935, "pending": 0, "committed": 65, "debt": 0 },
  "grants": [
    {
      "source": "trial",
      "amount": 500,
      "used": 65,
      "pending": 0,
      "remaining": 435,
      "startsAt": "2026-10-01T00:00:00.000Z",
      "expiresAt": "2026-12-19T00:00:00.000Z",
      "status": "active",
      "expiredUnused": null
    },
    {
      "source": "paid",
      "amount": 1500,
      "used": 0,
      "pending": 0,
      "remaining": 1500,
      "startsAt": "2026-10-01T00:00:00.000Z",
      "expiresAt": null,
      "status": "active",
      "expiredUnused": null
    }
  ],
  "spend": {
    "period": { "from": "2026-10-01T00:00:00.000Z", "to": "2026-11-01T00:00:00.000Z", "timeZone": "Europe/London" },
    "jobsCompleted": 1,
    "apiCalls": 3,
    "creditsSpent": 65,
    "jobCreditsSpent": 50,
    "apiCreditsSpent": 15,
    "byJobType": {
      "audio": { "jobs": 1, "credits": 50, "weight": 30, "unit": "minute", "units": 0.5 }
    }
  }
}

Body

FieldTypeDescription
balanceobjectavailable is what you can still spend (the string "unlimited" if you have an unlimited grant), pending is held for jobs still running, committed is spent from your active grants, and debt is any amount spent beyond what your grants covered.
grantsarrayEvery grant your organization has held, soonest-ending first, grants that never expire last — see the item shape below.
spendobjectWhat was spent in the period: jobsCompleted and apiCalls counts, creditsSpent (split into jobCreditsSpent and apiCreditsSpent), the period that was used, and byJobType with each job type's jobs, credits, and where it's priced per unit, the unit and units used.

grants item

FieldTypeDescription
sourcestringWhat kind of grant it is, such as "trial" or "paid".
amountnumber | stringCredits granted, or "unlimited".
used / pending / remainingnumberCredits spent from this grant, held for running jobs, and still available.
startsAt / expiresAtstring | nullISO 8601 times. expiresAt is null for a grant that never expires.
statusstring"active", "pending" (not started yet), "expired", or "revoked".
expiredUnusednumber | nullFor an expired grant, the credits that were left unused when it ended. null otherwise.

Responses

200Report, shown above. An organization with no grants gets an empty grants array rather than an error.
400from, to or tz isn't valid.
401Missing or invalid bearer token.
403Your token doesn't have the credits.read scope.

Metrics object

The shape of the metrics field inside Get result — one call's own emotion and voice-authenticity scores. Not a separate call: it's assembled for you as part of the result.

Requires the emotional-metrics.read scope

In addition to the conversations.read Get result itself needs, this one field also needs emotional-metrics.read — see Authentication & scopes. Without it, metrics is null and everything else in the response is unaffected.

Example

json
{
  "speechFileId": "6a9175051d000031000fcb4f",
  "day": "2026-09-16",
  "emotion": {
    "f": 0.5,
    "a": 0,
    "c": 0.5,
    "eri": 66.67,
    "sentimentScore": 0.06,
    "deltaSentiment": "neutral_to_neutral"
  },
  "deepfake": {
    "ali": 0.03,
    "scf": 1,
    "sra": 0.26,
    "speakerConfMean": -1,
    "silenceRatio": 0.56,
    "vulnerabilityLabel": "v-non-vulnerable"
  }
}

A call with no metrics yet

json
{ "metrics": null /* … rest of the result, unaffected … */ }

Fields

FieldTypeDescription
speechFileIdstringSame value as id in the enclosing Get result response.
daystring | nullThe call's date, YYYY-MM-DD.
emotion.f / a / cnumber | nullFrustration/Anxiety/Calm proportions for this one call. null (not zero) when the call was too short, too quiet on the customer's side, or didn't produce a sentiment-audio classification attributable to the customer — excluded from averages rather than treated as a neutral score.
emotion.erinumber | nullEmotional Risk Index, derived from f/a/c. null whenever any of the three is null.
emotion.sentimentScore / deltaSentimentnumber | null, string | nullThis call's overall sentiment score, and how it moved from start to end of the call (e.g. "neutral_to_negative").
deepfake.alinumber | nullAffect-Language Incongruence — how much this call's sentiment diverges from its own F/A/C. null whenever f/a/c is.
deepfake.scfnumber | nullSpeaker-Confidence Flatness, from the speaker-diarization classifier's own confidence scores.
deepfake.sranumberSilence-Ratio Anomaly, derived from the call's raw silence ratio.
deepfake.speakerConfMeannumberMean speaker-classifier confidence across the call. -1 is a real, expected value here, not an error — it isn't reserved for missing data the way null is elsewhere in this object.
deepfake.silenceRationumberRaw fraction of the call that was silence.
deepfake.vulnerabilityLabelstring | nullThe customer channel's own vulnerability classification for this call.

Job statuses

The three states a job can be in, returned by the status endpoint.

running

Still moving through the pipeline. Poll again shortly.

complete

Finished. The result endpoint has data for you now.

terminated

Stopped early by the pipeline itself — no result will follow for this job.

Errors

Every error response is a small JSON object with a human-readable message — with one exception: the network-level IP-allowlist 403 below. (Submit's own 403 for an unlicensed manifestId, and customer-profile's/agent-profile's own 403 for a missing scope, are not that exception — both are normal JSON responses.)

json
{ "message": "No job found with id 'e424667a-...'" }
400The request is missing something required — check the field table for the endpoint you called.
401Your Authorization header is missing, malformed, or the token isn't recognized.
403Either your origin IP isn't allowlisted yet — see Overview, blocked before it reaches the API itself, so the response won't be the usual JSON shape — or your token is missing the scope an endpoint needs, which is the usual JSON shape. See Authentication & scopes.
422The request was well-formed, but your organization isn't set up to process it yet, or (email/chat) the customer could not be determined.
409The conversation you resubmitted is still being processed, or changed type. Retry once the earlier job is complete.
413The JSON body is larger than the limit.
404Nothing matches that job id or phone number for your organization.
500Something failed on our end. Safe to retry with backoff.
503A service this API depends on (token verification, or the analytics store) is temporarily unavailable. Safe to retry with backoff — this is not a sign anything about your request was wrong.

Get your script

Fill in the base URL and token your Sentient Machines contact gave you, and this generates a ready-to-run copy of submit-and-fetch-result.sh with those values baked in — nothing you type here leaves this page.

submit-and-fetch-result.sh Template — placeholder values