Integration

How to send Streta a list and receive the rows. Generated from the code that runs; schema 2026-10.

• Send a list
• Send rows one at a time
• Your key
• What comes back
• The columns
• The webhook
• A recipe per tool
• What changes

Send a list

We enrich your list and never build one. What you send is used for your job and nothing else, and it isn't sold or shared. We find each business's own published line and ask it two or three plain questions. We never ring the person on your row.

The columns

A CSV with a header row. It needs a company_name column and, for each business, a city or domain (a website) so we can find its own line; a phone is optional and is kept as the contact's number, never rung. A state (two letters) on each row decides which state's rules apply to the call and the recording; a row with no state is closed as such rather than guessed.

Of everything else on your row, only ref (and the other keys of rows merged into it) and domain are returned; the rest is used for your job and kept for you. A phone on a row with a city or website is the contact's number, kept as storage; we ring the listing's line and the file says your_number_differed: yes.

Your own key for each row comes back on the row as ref: send it as row_id or ref, or as any column that starts ref_. If a file sends several, row_id wins, then ref, then the first ref_ column.

Headers we read as ours

Headers are read in any case and spelling ("Company Name" is company_name). These are read as the column on the left unless the file already has that column:

The reader takes a comma, semicolon, tab or pipe as the separator, UTF-8 or Windows-1252, and a short row (its last cells blank). A file with the wrong columns is refused with the headers we found, and the response lists the names we read yours as (mapped_columns). The most one upload carries is 20 MB.

Rows we don't ring

A mobile line, a business in a state closed to an artificial voice, a row with no state, and a business whose own line we can't find aren't rung. Each comes back as a row, with the reason in words and as a value (not_called_reason), so every business you send that we could name comes back as a row, and the ones we didn't call are yours to call. A row with nothing to name (a duplicate of another row, no company name, no city or website, a number on our stop list) is on the list of rows we could not take, below.

Look before it dials

Add dry_run=true to the same request. It resolves the list, counts what would happen (found, not found with the reason, mobile, closed state, no state, how many numbers we would ring from) and writes nothing and rings no one. Read the counts with us before the first job.

curl -X POST "https://streta.ai/jobs?mission_id=$MISSION_ID&dry_run=true" \
  -H "X-API-Key: $STRETA_KEY" \
  -F "file=@list.csv"

import requests

r = requests.post(
    "https://streta.ai/jobs",
    params={"mission_id": MISSION_ID, "dry_run": "true"},   # drop dry_run to create the job
    headers={"X-API-Key": STRETA_KEY},
    files={"file": open("list.csv", "rb")},
)
print(r.status_code, r.json())

Send rows one at a time

A CRM that posts each new lead, a Clay column or a script can send rows into a mission that already exists, without a file. The mission is in the path; the rows are one object, a list of objects, or {"rows": [...]}, with the same column names a file takes (the header aliases above are read here too). Your own id for each row goes in ref.

curl -X POST "https://streta.ai/missions/$MISSION_ID/rows" \
  -H "X-API-Key: $STRETA_CLIENT_KEY" -H "Idempotency-Key: lead-2041" -H "Content-Type: application/json" \
  -d '{"company_name": "Heights Tire", "city": "Houston", "state": "TX", "ref": "crm-2041"}'

The answer is 202 and one entry per row, at once: {ref, streta_id, status}. streta_id is the id the row will carry in your file and in the webhook's sortie.id; ref is yours. The result of each row reaches your webhook per row, as it closes, and the file has it by wave. (A row that is the same business as another row you sent is merged into the first when the list is planned; the webhook's merged_refs says so.)

Idempotency-Key is one per request (up to 200 characters): the same key again is answered with the rows it already made and books nothing. A ref this mission already has is answered already_accepted with the id it has, so a retry with a new key does not book a business twice. Send a ref on every row.

Rows go to the mission's job for the UTC day, made on the first row of the day. It is an ordinary job: the same pace, the same file, and job.finished when the day is over and its rows are closed. A client's first job is created held for a day so its counts are read before anybody is rung; the answer says held_until. The checks the file meets apply here (a number to ring from, the approved lines, the carrier). To look before you send, send a file with dry_run=true.

Your key

An account key is Streta's to give an agency; a client of its own has a key of its own. A person at your file makes it: /file, Settings, "A key for your tools" (Make a key). It is shown once and only its last four characters are kept; make one for each tool and revoke one without touching the rest. Send it in an X-API-Key header.

The key is one client's. It reads that client's rows and posts rows into that client's missions, and every other route answers 403:

To pull what is new, ask for closed_since with the instant of your last pull; the response header X-Streta-Next-Cursor is the instant to ask from next time, and a pull that finds nothing new returns the one it was asked from.

What comes back

Every business we complete comes back as one of three results, in result_key: matches (the answer you were looking for), no_match (a definitive answer that isn't), or no_answer (no definitive answer, with the reason). A business that asked us to stop comes back as exactly that; honor it in your own outreach. A call that failed on our side is retried and is never shown to you or charged.

Each column is one of two kinds. Observable is what happened or is on the record: whether a person answered, the answer, the quote. Inferred is our reading, kept in separate columns whose keys end _inferred, and is never stored as a fact. Weight the two as you like.

Rows we could not take, and rows we could not complete

Every row you send is one of: a row of the file (a result, or a business we named and did not call, with the reason), a row we could not take, or a row we could not complete. The first three counts of job.finished are the file's, and the other two make rows sent reconcile with rows back: counts carries matches, no_match, no_answer, not_accepted, not_completed.

Could not take are rows with nothing to make into a call. They are not results, not a count on your page and not billed. They are a list, GET /jobs/{id}/not_accepted (JSON, or format=csv), and on /file a quiet download on the job page, each with your ref, the company, one reason from this closed set and the reason in words:

A business we could name and did not call (no listing, a closed one, no phone, on our stop list) is also a row of the file, no_answer, "Not called by us: …". Could not complete are rows our own call failed on: never shown as a result, never charged, counted as not_completed and said on your page as "N rows we could not complete; not charged".

Where a row stands

GET /jobs/{id}/progress lists every row with your ref and one of these statuses, and result once finished:

A list over 2,000 rows to look up is answered 409 with its estimate until the request carries confirm_spend=true. A second file, suppression (a CSV with a phone and/or domain column), is your own do-not-contact list: a row on it is not called, comes back no_answer with that reason, and is read for that job only. GET /stops is every business that asked us to stop, with the day and their words, for your sequencer. POST /rows/{streta_id}/outcome says what came of a row.

The columns

The same keys, in this order, on every row, whatever its result; a key that doesn't apply is blank. Keys never change and are only added, at the end. A question's sentence is published once, in questions and in the column's label, never in a key (q1_answer is question 1 whichever words it was asked in). The labels below are for a mission that asks the three example questions.

Where a key takes a closed set of values, here they are:

Of what you sent, a row comes back with ref and merged_refs (your own keys) and domain (the website you sent). Nothing else on your row is returned: join on ref. A row we did not ask because this mission already has the business's answer is by prior, with the earlier answer and its date, and answered_before_streta_id names the earlier row. A row whose answer is the business's own published words, with nobody reached to confirm them, is by research: research_words is their sentence word for word, research_where says where it was said, and not_tested says what the phone could not test. When a call did reach someone, research_call says whether it confirmed or contradicted the published words, and the answer is the call's.

The webhook

Set the URL on your file's settings page; the signing secret is shown once. Each finished row is a POST of JSON. Answer with a 2xx at once and do your work after.

Events

Order and repeats

Deliveries are sent in order per row. sequence is your deliveries in order; version is this row's. Apply a delivery only if its version is greater than the one you hold for that sortie.id. A resend carries the same id, sequence and version.

Retries

If your receiver is down we try again after 1 minute, 5 minutes, 1 hour, 6 hours; a 4xx other than 429 is taken as your bug and isn't retried. A failed delivery is on your settings page and can be resent from there.

Signature

Each request carries Streta-Signature: t=<seconds>,v1=<hex>, where v1 is the HMAC-SHA256, with your secret, of "<t>." + the raw body. Check it over the body exactly as received, and refuse a timestamp more than a few minutes old.

import hashlib, hmac, time

def verify(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, v1 = int(parts["t"]), parts["v1"]
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), str(t).encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

# in your handler: verify(SECRET, request.body, request.headers["Streta-Signature"])

const crypto = require("crypto");

function verify(secret, rawBody, header, tolerance = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split(/=(.*)/s).slice(0, 2)));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > tolerance) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.`).update(rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(parts.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// rawBody is the request body exactly as received (a Buffer), not re-serialized JSON

# the header: Streta-Signature: t=<seconds>,v1=<hex>
printf '%s.%s' "$T" "$(cat body.json)" | openssl dgst -sha256 -hmac "$SECRET" -hex   # compare to v1

A sample row

This is the whole payload of a row, as Send a sample row sends it to your receiver (built from your own mission once you have one).

{
  "id": "5d9c2a40-1111-4222-8333-444455556666",
  "event": "row.sample",
  "test": true,
  "schema": "2026-10",
  "sent_at": "2026-10-20T15:04:05+00:00",
  "client": {
    "id": "c0ffee00-1111-4222-8333-444455556666",
    "name": "Your company"
  },
  "sequence": null,
  "version": null,
  "mission": {
    "id": "a1b2c3d4-1111-4222-8333-444455556666",
    "name": "Sample mission",
    "objective": "Do they have a snack machine for customers?"
  },
  "job": {
    "id": "e5f6a7b8-1111-4222-8333-444455556666",
    "name": "DFW tire shops"
  },
  "sortie": {
    "id": "7c1f2a90-0000-4000-8000-000000000001"
  },
  "questions": [
    {
      "key": "q1",
      "line": "do y'all have a waiting area?",
      "qualifier": false
    },
    {
      "key": "q2",
      "line": "are there snacks for customers?",
      "qualifier": true
    },
    {
      "key": "q3",
      "line": "when are y'all least busy?",
      "qualifier": false
    }
  ],
  "columns": [
    {
      "key": "ref",
      "label": "ref",
      "kind": "observable"
    },
    {
      "key": "merged_refs",
      "label": "merged_refs",
      "kind": "observable"
    },
    {
      "key": "streta_id",
      "label": "streta_id",
      "kind": "observable"
    },
    {
      "key": "job",
      "label": "job",
      "kind": "observable"
    },
    {
      "key": "company",
      "label": "company",
      "kind": "observable"
    },
    {
      "key": "phone",
      "label": "phone",
      "kind": "observable"
    },
    {
      "key": "city",
      "label": "city",
      "kind": "observable"
    },
    {
      "key": "domain",
      "label": "domain",
      "kind": "observable"
    },
    {
      "key": "result_key",
      "label": "result_key",
      "kind": "observable"
    },
    {
      "key": "result",
      "label": "result",
      "kind": "observable"
    },
    {
      "key": "answered_on",
      "label": "answered_on",
      "kind": "observable"
    },
    {
      "key": "what_we_found",
      "label": "what we found",
      "kind": "observable"
    },
    {
      "key": "answer",
      "label": "answer",
      "kind": "observable"
    },
    {
      "key": "quote",
      "label": "quote",
      "kind": "observable"
    },
    {
      "key": "asked_not_to_be_contacted",
      "label": "asked_not_to_be_contacted",
      "kind": "observable"
    },
    {
      "key": "instrument",
      "label": "instrument",
      "kind": "observable"
    },
    {
      "key": "by",
      "label": "by",
      "kind": "observable"
    },
    {
      "key": "your_number_differed",
      "label": "your_number_differed",
      "kind": "observable"
    },
    {
      "key": "q1_answer",
      "label": "1. do y'all have a waiting area?",
      "kind": "observable"
    },
    {
      "key": "q1_words",
      "label": "1. their words",
      "kind": "observable"
    },
    {
      "key": "q1_reading_inferred",
      "label": null,
      "kind": "inferred"
    },
    {
      "key": "q2_answer",
      "label": "2. are there snacks for customers?",
      "kind": "observable"
    },
    {
      "key": "q2_words",
      "label": "2. their words",
      "kind": "observable"
    },
    {
      "key": "q2_reading_inferred",
      "label": "2. our reading (inferred)",
      "kind": "inferred"
    },
    {
      "key": "q3_answer",
      "label": "3. when are y'all least busy?",
      "kind": "observable"
    },
    {
      "key": "q3_words",
      "label": "3. their words",
      "kind": "observable"
    },
    {
      "key": "q3_reading_inferred",
      "label": null,
      "kind": "inferred"
    },
    {
      "key": "ended_before_qualifier",
      "label": "ended before the qualifier",
      "kind": "observable"
    },
    {
      "key": "ended_early_words",
      "label": "ended early: their words",
      "kind": "observable"
    },
    {
      "key": "ended_early_reading_inferred",
      "label": "ended early: our reading (inferred)",
      "kind": "inferred"
    },
    {
      "key": "manner_reading_inferred",
      "label": "their manner: our reading (inferred)",
      "kind": "inferred"
    },
    {
      "key": "manner_heard",
      "label": "their manner: what we heard",
      "kind": "observable"
    },
    {
      "key": "called_back",
      "label": "called us back",
      "kind": "observable"
    },
    {
      "key": "called_back_from",
      "label": "called back from",
      "kind": "observable"
    },
    {
      "key": "called_back_from_line_kind",
      "label": "called back from: line kind",
      "kind": "observable"
    },
    {
      "key": "called_back_words",
      "label": "called back: their words",
      "kind": "observable"
    },
    {
      "key": "context_status",
      "label": "context: status",
      "kind": "observable"
    },
    {
      "key": "context_listing",
      "label": "context: their listing",
      "kind": "observable"
    },
    {
      "key": "context_website",
      "label": "context: their website",
      "kind": "observable"
    },
    {
      "key": "context_web",
      "label": "context: elsewhere on the web",
      "kind": "observable"
    },
    {
      "key": "context_reviews",
      "label": "context: customer reviews",
      "kind": "observable"
    },
    {
      "key": "context_reading_inferred",
      "label": "context: our reading (inferred)",
      "kind": "inferred"
    },
    {
      "key": "context_could_not_read",
      "label": "context: could not read",
      "kind": "observable"
    },
    {
      "key": "stop_requested_on",
      "label": "stop requested on",
      "kind": "observable"
    },
    {
      "key": "stop_request_words",
      "label": "stop request: their words",
      "kind": "observable"
    },
    {
      "key": "no_answer_reason",
      "label": "no answer reason",
      "kind": "observable"
    },
    {
      "key": "not_called_reason",
      "label": "not called reason",
      "kind": "observable"
    },
    {
      "key": "answered_before_streta_id",
      "label": "answered before: streta_id",
      "kind": "observable"
    },
    {
      "key": "answered_by_said",
      "label": "answered by: what they said",
      "kind": "observable"
    },
    {
      "key": "would_know_inferred",
      "label": "would they know: our reading (inferred)",
      "kind": "inferred"
    },
    {
      "key": "research_words",
      "label": "research: their words",
      "kind": "observable"
    },
    {
      "key": "research_where",
      "label": "research: where it was said",
      "kind": "observable"
    },
    {
      "key": "research_call",
      "label": "research: what the call found",
      "kind": "observable"
    },
    {
      "key": "not_tested",
      "label": "not tested",
      "kind": "observable"
    },
    {
      "key": "called_back_caller_id_check",
      "label": "called back from: caller ID check",
      "kind": "observable"
    },
    {
      "key": "context_job_posts",
      "label": "context: their job posts",
      "kind": "observable"
    },
    {
      "key": "context_dns",
      "label": "context: their DNS",
      "kind": "observable"
    }
  ],
  "row": {
    "ref": "crm-1042",
    "merged_refs": "crm-1077;crm-1090",
    "streta_id": "7c1f2a90-0000-4000-8000-000000000001",
    "job": "DFW tire shops",
    "company": "Cowtown Tire",
    "phone": "+18175550142",
    "city": "Fort Worth",
    "domain": "cowtowntire.example",
    "result_key": "matches",
    "result": "Matches your objective",
    "answered_on": "2026-10-20",
    "what_we_found": "Spoke with someone at the shop: no snack machine.",
    "answer": "no",
    "quote": "No, we just have a coffee pot.",
    "asked_not_to_be_contacted": "",
    "instrument": "ai",
    "by": "call",
    "your_number_differed": "yes",
    "q1_answer": "yes",
    "q1_words": "Sample: the business's words for q1.",
    "q1_reading_inferred": "Sample: our reading for q1. Inferred.",
    "q2_answer": "no",
    "q2_words": "Sample: the business's words for q2.",
    "q2_reading_inferred": "Sample: our reading for q2. Inferred.",
    "q3_answer": "no",
    "q3_words": "Sample: the business's words for q3.",
    "q3_reading_inferred": "Sample: our reading for q3. Inferred.",
    "ended_before_qualifier": "no",
    "ended_early_words": "Sample: words when a call ended early.",
    "ended_early_reading_inferred": "Sample: our reading of why it ended early.",
    "manner_reading_inferred": "Sample: our reading, relaxed and helpful.",
    "manner_heard": "Sample: unhurried, answered at once.",
    "called_back": "no",
    "called_back_from": "+18175550199",
    "called_back_from_line_kind": "business line",
    "called_back_words": "Sample: returning your call, we don't have one.",
    "context_status": "found",
    "context_listing": "Sample: independent tire shop, open 8 to 6, waiting area.",
    "context_website": "Sample: family owned since 1987.",
    "context_web": "Sample: mentioned in a local list of tire shops.",
    "context_reviews": "Sample: customers mention a clean waiting room.",
    "context_reading_inferred": "Sample: our reading of the context.",
    "context_could_not_read": "",
    "stop_requested_on": "",
    "stop_request_words": "",
    "no_answer_reason": "",
    "not_called_reason": "",
    "answered_before_streta_id": "Sample: our reading for an. Inferred.",
    "answered_by_said": "Sample: our reading for an. Inferred.",
    "would_know_inferred": "Sample: our reading for wo. Inferred.",
    "research_words": "Sample: the business's words for re.",
    "research_where": "Sample: our reading for re. Inferred.",
    "research_call": "Sample: our reading for re. Inferred.",
    "not_tested": "Sample: our reading for no. Inferred.",
    "called_back_caller_id_check": "Sample: our reading for ca. Inferred.",
    "context_job_posts": "Sample: our reading for co. Inferred.",
    "context_dns": "Sample: our reading for co. Inferred."
  },
  "inferred_columns": [
    "q1_reading_inferred",
    "q2_reading_inferred",
    "q3_reading_inferred",
    "ended_early_reading_inferred",
    "manner_reading_inferred",
    "context_reading_inferred",
    "would_know_inferred"
  ],
  "message": "This is a sample row from Streta. It isn't a business, it isn't billed and it isn't in your file."
}

A recipe per tool

Clay

Export the table as a CSV and send it as above, or send it from a script on a schedule. To receive rows, add a table with a Webhook source in Clay and put its URL in your Streta file settings: each row.finished arrives as one record and the fields are under row. Clay can't check the signature, so keep the URL secret.

Zapier

Trigger: Webhooks by Zapier, Catch Hook; paste its URL into your Streta file settings and press Send a sample row to teach Zapier the fields. Zapier can't verify the signature; keep the URL secret. Use row.result_key to filter (matches, no_match, no_answer) and row.ref to find your own record.

Make

Scenario with a Custom webhook module; paste its address into your file settings and press Send a sample row so Make learns the structure. Filter on row.result_key; route row.updated and row.withdrawn events to update or delete the record that carries the same sortie.id.

n8n

A Webhook node (POST, respond immediately with 200). To verify the signature, add a Code node that runs the Node.js function above over the raw body (set the Webhook node's Raw Body option).

A script or your own server

Receive POST requests, verify the signature with the function above, answer 2xx at once, and do your work after you have answered. Key your records on sortie.id and apply a delivery only if its version is greater than the one you hold.

What changes

The schema is 2026-10. A key is never renamed or removed and a new one is added at the end of row, so a receiver that reads the keys it knows keeps working. A change that cannot be made that way gets a new schema value, announced here before it is sent.

Questions: hello@streta.ai.