Create a contact

Creates a contact and runs the full signup pipeline: deduplication, referral credit, trust scoring, the verification email, webhooks and automations. This is the same path a Launch page submission takes, so nothing is skipped.

One call returns the referral code, the live queue position and the trust verdict, so you do not need a second request to show someone their place in line.

Body parameters#

Email addresses are canonicalized before deduplication, so common Gmail misspellings resolve to the same person rather than creating two.

Subscription and verification#

A new signup is subscribed at once: joining is agreeing to hear from you, so status is subscribed and consent is signup. Whether they are also sent an email to verify their address is the form's own setting, Ask people to verify their email. The API takes no override: the form decides, the same as for a signup on your page. If you want a different answer, capture through a different form. The one addition is the project's Hold referrals until the friend verifies: when it is on, a new signup you pass a referred_by for is sent the link even if the form doesn't ask.

verification in the response says where they stand on proving their address. It is separate from status:

waiting means a verification email is due, not that it has gone out: a guard can still hold it back, for example when the address is known to bounce.

What comes back#

The response is a full contact object plus verification, above. A few fields answer differently than you might assume:

referral.state is null for somebody nobody referred, and pending_verification for a brand new signup who came through a referral link, because credit has not been given yet: it waits for them to verify when the form asks them to or the project holds referrals until the friend verifies (then they are sent the link even though the form doesn't ask), and otherwise follows moments after the call. See referrals for the full list of states.

Headers#

Errors#

Every failure uses one envelope, so a client parses a single shape for all of them. param and errors are present only when a specific field is at fault:

{
    "error": {
        "type": "invalid_request_error",
        "code": "parameter_invalid",
        "message": "One of `email`, `phone` or `identifier` is required.",
        "param": "email",
        "errors": {
            "email": ["One of `email`, `phone` or `identifier` is required."]
        },
        "request_id": "req_01jq8zk3m7xn2vb4rd5eempt9h"
    }
}

Worth knowing#

• Capture never fails for billing reasons. If the workspace is over its plan's contact limit, the signup is still stored. The response returns locked: true and withholds the identity until the plan is upgraded. Nobody's signups are ever refused or deleted over a plan cap.
• Positions come from Redis, not a table scan, so this call stays fast at a million contacts.
• Referral credit follows verification. Passing referred_by records who sent this person right away, but the referrer's count moves when the new signup verifies. On a form that does not ask people to verify there is nothing to wait for, so the credit lands at creation, unless the project holds referrals until the friend verifies: then they are sent the link and the credit waits for the click.
• A stage with the invited role mints an invitation. That is not this endpoint, but it is worth knowing before you move somebody with update.
• Every response carries a Request-Id. Quote it in support and we can find the exact call.