Skip to main content
Changes to the REST API that can affect an integration. Each entry says what changed and whether you need to do anything.
Contact lists: tag a contact to have it called next
This adds an optional field. Nothing you send today changes.
  • Add a contact to a list takes tag, a short label such as "Hot lead" (24 characters at most). A tagged contact goes to the top of the list and of its dialing queue at once, with no reimport. If the list’s owner is dialing that list, it is their next call, right after the call in progress, and they get a notification.
  • If the list already holds the person (same email, or same phone number and first name), that contact moves to the top and takes the tag instead of a second one being added.
  • Get a contact list returns tag and tagged_at on tagged contacts.
What to do: nothing, unless you want hot leads called first: send tag with them. A contact added without tag is appended as before and reaches the dialing queue at the next reimport. For a step-by-step setup, see Call new leads within minutes.
Sequencer: variables, routing, phone numbers and email drafts
Everything here adds to the Sequencer API. Nothing you send today stops working, except a template or step text with a mistyped variable, which is now refused rather than sent with the typo.

Templates

  • Use every variable the app offers in a subject or body: the person, their company, the sending rep (sender.*) and your custom fields, with a fallback for an empty value ({{first_name|there}}). See Create an email template.
  • Choose what happens when a variable is empty and has no fallback with if_empty: wait holds the email for the rep, send sends it with the gap.
  • A token that is not a variable, or a custom field your team does not have yet, is refused with 400 and code: unknown_variables, listing each one. Preview lists them as unknown.
  • Templates and tasks show their files in a read-only attachments list.
What to do: a template you create through the API now defaults to if_empty: wait, so an automatic email with an empty variable becomes a task for the rep instead of going out with a gap. Send "if_empty": "send" to keep sending. Templates saved before keep behaving as send.A template saved before the check that still holds a token that is not a variable is no longer sent as typed: each email from it is held as a task for the rep, such as Waiting for you: {{account}} isn't a variable. Preview your templates and fix anything listed in unknown.

Steps

  • Name a call or to-do step, and write any step’s note, with variables: Call {{first_name}} at {{company}}.
  • Turn on personalization for an email step, so each person’s email is written for them.

Adding people

  • Send phone_numbers (up to 10) and website with each prospect, and a LinkedIn profile URL in linkedin_username.
  • See who a rule started in another sequence instead: routed when you add contacts, and routed_count on enrollment runs.
  • Ask the enrollment preview for routing and call history with include_routing and include_call_history.
What to do: the refusals list can return reason: routed, for someone a rule started in another sequence, so handle a reason you don’t know. The preview’s routed and excluded_no_phone statuses only appear when you send include_routing.

Rules of engagement

  • Write rules on call history (prior_calls, last_call_result, had_call_result), start people in another sequence with route_to_sequence, and limit any rule to some sequences with sequences.
What to do: when you update a policy, send each rule back with its sequences, or the rule starts applying to every sequence.

Tasks

  • Draft a manual email for the rep with body when you create or bulk create a task, or on any open manual email task, cadence tasks included. A body is plain text and is sent as written: variables are not filled in, and an email that still has a {{...}} is not sent.
  • Bulk create says why each contact got no task, with a code and the person’s name.
What to do: completing a task from a sequence without subject sends the step template’s subject, not the one you set on the task. Pass subject again when you complete it.

Timeline

  • The timeline filters moved, move_refused, result_changed, routed and rescheduled are now documented. The API already accepted them.

Reference corrections

  • The reference now states limits the API already enforced: a prospect’s linkedin_username and a custom field’s label can’t be empty, a label is at most 200 characters, and a preview_id at most 100.
Page sizes, validated queries and fixes

A limit above the maximum is treated as the maximum

A list request whose limit is above its maximum now gets the maximum instead of 400: 100 on every list, 200 for sending mailboxes and 25 for enrollment runs. GET /v1/call-log, GET /v1/scored-calls and the contact-list pages had no maximum before and now return at most 100 per page. Every page reports the limit it used; the call-log page without filters, the contact-list and follow-up pages and the snoozed-contact list gained the field. A limit that is not a positive number still fails with 400. What to do: if you ask for more than 100, compare the limit in the response with what you sent and keep paging.

Call-log and scored-call queries are validated

GET /v1/call-log and GET /v1/scored-calls now check and convert their query parameters:
  • A list filter takes a single value without [], such as filters[user_ids]=ID. It used to fail with 500.
  • filters[exclude_negative_dispositions]=false leaves the filter off. It used to turn it on.
  • start_date, end_date, min_score and max_score on scored calls work. They used to return an empty page.
  • A value that does not fit its parameter, such as an unknown outcome, a date that does not parse or a score that is not a number, fails with 400. Unknown parameters are still dropped.
What to do: drop any workaround for these, such as filtering scored calls in your own code.

Fixes

  • PUT /v1/snoozed-contacts/{id} accepts snooze_until, so a snooze’s end date can be changed.
  • Creating, editing and pinning a note, and reading or updating one snoozed contact, return the record in the documented shape. They used to wrap it in internal fields.
  • GET /v1/snoozed-contacts returns each record’s real _id, team and contact_list. They used to be regenerated on every request.
  • An ID that is not valid answers 400, not 500, on the contact-list, snoozed-contact and note endpoints and in analytics user_ids.
  • Phone lookup callbacks no longer include the contact’s email addresses. Use an email lookup for those.
Reference corrections

Errors the API could already return

The Errors page now covers every status the API can answer with, not only the common ones: 413 for a body over the size limit (10 MB on /v1/contact-lists and /v2/sequencer, 1 MB elsewhere), 422 when the Sequencer’s rules refuse a request, 502 and 504 when a service behind the API cannot be reached or does not answer within 55 seconds, and 405 on /v2/sequencer during planned maintenance. It also says which 403s are about the acting user_id rather than the key, and the order the checks run in. Nothing in the API changed. What to do: treat 413 and 422 as not retryable, and 502 and 504 like a 5xx.

Pagination envelopes and IDs

The API Reference now lists the five pagination envelopes the v1 and v2 lists use, and the IDs that are not 24-character hexadecimal strings: disposition and sending-mailbox IDs are integers, CRM sequence IDs are the CRM’s own, and enrollment-run IDs start with enroll_. Nothing in the API changed.

Webhook delivery

Webhooks are now documented in one place, with the events, the payload shape and the delivery rules. Two facts were missing before: a CALL_LOGGED subscription is sent only for calls whose disposition is ticked on it, and the dashboard does not display the signing secret, so x-salesfinity-signature cannot be checked yet. Keys and webhooks are created under Settings → Connections → API & Webhooks.

The OpenAPI description

The OpenAPI description now matches what the API sends, with no operation, parameter or field removed:
  • Every successful response documents the X-Request-Id and X-RateLimit-* headers, and every error response documents X-Request-Id.
  • request_id is a required field of the error body, and every error example carries it.
  • Every /v2/sequencer operation documents 502 and 504.
  • Sequencer events list the fields they already returned: team, sequence_state, task, user, external_id, created_at and updated_at.
  • Request fields carry the length limits the API already enforced, and descriptions state the defaults, units and conditions that were missing, such as primary_reply_pause_duration being in seconds and a schedule needing all five fields.
Nothing in the API changed. What to do: regenerate any client built from the description.

Known issues now documented

Some endpoints do not behave as documented before, and their reference pages now say so with a workaround: a snoozed contact’s snooze_until cannot be changed, the date and score filters on GET /v1/scored-calls return no results, and a few Sequencer responses expand fields that the schema types as IDs. The contact-list, snoozed-contact and note endpoints answer 500, not 400, for an ID that is not 24 hexadecimal characters, and so do the analytics endpoints for such an ID in user_ids. What to do: read the warning on the reference page of any of these endpoints you call, and check IDs before sending them.
Rate limits, safe retries and request IDs

Rate limits for every endpoint

Every endpoint is now rate limited per team, and all of a team’s API keys share the limits. Requests are counted in fixed one-minute windows that start on the minute:Every response to an authenticated request carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 carries Retry-After, the seconds to wait. Before this change only /v2/sequencer/* was limited, at 120 requests per minute. We give notice before lowering any limit. What to do: wait for Retry-After on a 429. See Rate limits.

Idempotency-Key on every Sequencer POST

Every POST /v2/sequencer/* endpoint except the three /preview endpoints now accepts an Idempotency-Key header. A retry with the same key replays the original response; the same key with a different body or path, or while the first request is still running, returns 409. Keys are kept for 24 hours per team. POST endpoints outside the Sequencer are still not idempotent. See Retrying writes safely.

Internal fields removed from Sequencer settings

GET /v2/sequencer/settings no longer returns the three internal fields about the team’s sending account: its account ID and its two provisioning timestamps. What to do: stop reading them if you do. To find out why a sequence with email steps will not enable, read the team’s mailboxes with GET /v2/sequencer/email-accounts: enabling needs at least one mailbox the sequence sends from with is_connected and can_send true and is_paused false.

Request IDs and one error body for every error

Every response carries an X-Request-Id header. Send your own to trace a request, or let us generate one. Every error body now has the same four fields, statusCode, error, message and request_id, including errors raised while reading the request, such as malformed JSON or an oversized body. Status codes and messages are unchanged. What to do: log request_id and include it when you contact support. See Errors.

Webhook event IDs

Every webhook delivery carries an x-salesfinity-event-id header that stays the same across retries of the same event. A delivery that times out, cannot connect, or gets a 429 or a 5xx is attempted up to 3 times in total. The payload is unchanged. What to do: skip events whose ID you have already processed. See Webhooks.

Webhook URLs must be public

Creating a webhook, or changing its URL, is refused unless the URL is a public http or https address: not localhost, and not a private, loopback or link-local IP address. Existing webhooks keep working until their URL is changed. What to do: point webhooks at a publicly reachable address.

Rate-limit and request-ID headers readable in browsers

Responses now list X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After and X-Request-Id in Access-Control-Expose-Headers, so browser code can read them. Nothing changes for server-side clients.

Enrichment callback_url must be public

POST /v1/api/enrichment/email and POST /v1/api/enrichment/phone now reject, with 400, a callback_url that is not a public http or https URL: localhost, and private, loopback or link-local IP addresses. Requests already accepted are unaffected. What to do: point callbacks at a publicly reachable address.

Reference corrections

GET /v1/follow-up is now documented with the shape it has always returned: the page position is under pagination (total, page, next), not at the top level.

Next steps

Handle API errors

Status codes, error bodies, and what to retry.

Stay under the rate limits

Read the limit headers and back off before you hit a 429.