Skip to main content

    Developers

    Lead API

    Send leads from your own forms into Workky with one HTTPS request.

    Overview

    POST a JSON body to the lead endpoint with your lead key in a header. Workky matches the person by phone or email, or adds them as a new lead, writes a lead line on their activity and tells the owner once.

    POST https://app.workky.ai/api/integrations/leads

    Keys

    Create a key in Workky under Connections, Lead keys. It starts with wk_live_ and is shown once. Keep it on your server: never in a browser, an app or a public repository. A workspace can hold 10 active keys. Revoke a key there and it stops at once.

    X-Workky-Integration-Key: wk_live_your_key

    Send a lead

    curl -X POST https://app.workky.ai/api/integrations/leads \
  -H "Content-Type: application/json" \
  -H "X-Workky-Integration-Key: $WORKKY_LEAD_KEY" \
  -d '{ "externalId": "form-8841", "name": "Jane Rivera", "phone": "+14155550142", "email": "jane@example.com", "source": "Website form", "notes": "Asked for an appointment next week" }'

    Fields

    FieldRequiredMaxMeaning
    externalIdYes120Your own id for this lead. Sending the same id again returns the first answer and never makes a second lead.
    nameYes120The person's name as they typed it.
    phonePhone or email40With the country code, for example +14155550142. A bare 10-digit number is read as a US number.
    emailPhone or email254Stored in lower case.
    sourceNo80Where the lead came from, shown next to it in Workky.
    notesNo500What the person wrote in a free-text box.
    companyNo120Their business, if your form asks.
    industryNo80Their line of work, if your form asks.
    interestNo80What they asked about.

    Responses

    StatusMeaning
    201 createdA new person was added as a lead.
    200 updatedA person with this phone or email already existed. Missing details were added and a lead line written.
    200 duplicateThis externalId was already received. The first answer is returned; nothing changes.
    400A field is missing, too long or not valid. The error says what to fix. Send again with the same externalId.
    401The key is missing, mistyped or revoked. Nothing was stored.
    429Too many requests. Wait the seconds in Retry-After, then send again.
    503An earlier request with this externalId was cut off. Send it once more (Retry-After: 1).
    { "status": "created", "externalId": "form-8841", "customerId": 512 }

    Limits and retries

    • 120 requests a minute per key, and 240 a minute from one address.
    • Always send an externalId. Retrying with the same one is safe: a lead is never stored twice.
    • Retry on 429 and 503 after Retry-After. Do not retry a 400 or 401 without fixing it.
    PreviousTeam and rolesNextTroubleshooting