TextKitDocs

Connect a tool

Connects a tool with its API key or service account, the same as the console's Integrations page: the credentials are proved with one read, then sealed and never returned.

POST/v1/integrations

Body Parameters

  • providershopify, hubspot, salesforce, mixpanel, amplitude, webhookrequired
  • modepull, push

    Mixpanel / Amplitude: pull with credentials every 6 hours (default when credentials are sent), or push: no credentials, the tool's cohort sync posts to the ingest URL.

  • namestring

    What to call it (default: the tool and its source).

  • sourceIdstring

    Mixpanel or Amplitude cohort id; HubSpot list id; Salesforce campaign id; a Shopify customer search. Blank = everyone (HubSpot, Shopify, Salesforce).

  • projectIdstring

    Mixpanel project id.

  • regionus, eu

    Mixpanel / Amplitude data residency.

  • usernamestring

    Mixpanel service account username.

  • secretstring

    Mixpanel service account secret.

  • apiKeystring

    Amplitude API key.

  • secretKeystring

    Amplitude secret key.

  • accessTokenstring

    HubSpot private app token, or Shopify Admin API access token.

  • shopDomainstring

    Shopify store, like acme.myshopify.com.

  • instanceUrlstring

    Salesforce My Domain URL.

  • sfObjectContact, Lead
  • clientIdstring

    Salesforce consumer key, or Shopify client id.

  • clientSecretstring

    Salesforce consumer secret, or Shopify client secret.

  • phoneFieldstring

    The tool's property holding the mobile number, when not the usual one ($phone, phone, mobilephone).

  • consentFieldstring

    The tool's property that records SMS consent (e.g. sms_opt_in).

  • consentEventstring

    Mixpanel / Amplitude: the opt-in event the cohort is built on (e.g. SMS Opt In). Everyone in the cohort is recorded as opted in, from that event.

  • phoneEventstring

    Mixpanel: an event that carries the number when profiles do not (e.g. Verification Check Success). A member with no phone on the profile gets it from their latest such event.

  • phoneEventPropertystring

    Mixpanel: that event's property holding the number (default phone).

Details

Its people sync into a list of their own every 6 hours (and on POST /v1/integrations/{id}/sync). Consent comes across only from the field or opt-in event you name.

A push integration (provider webhook, or Mixpanel / Amplitude with mode "push") answers ingest_url and ingest_token once. Scope: contacts.

Responses

  • 201JSON object

    The integration (with ingest_url and ingest_token once, for push)

  • 401Error

    Missing, malformed, or revoked API key

  • 402Error

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 429Error

    Rate limit or quota exceeded

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

  • 401

    Missing, malformed, or revoked API key

  • 402

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 429

    Rate limit or quota exceeded