Kraya-AI Docs
Integrations

Connect Kraya API

Push lead data between Kraya and external systems using the REST API.

Overview

Connect Kraya (External API) allows your external systems to create or update leads in Kraya via a secure HTTP API. This is useful when you already have a backend system and want to push leads into Kraya directly without manual entry.

The API uses a unique slug and API key for authentication, supports phone-based deduplication (upsert), and can automatically assign pipelines, stages, and Auto Followup sequences.

What you can do

  • Create new leads or update existing leads via HTTP POST requests
  • Automatically assign leads to specific pipelines and stages
  • Assign Auto Followup sequences to leads upon creation/update
  • Set custom attributes that match your organization's default attributes
  • Configure default country code for phone number normalization
  • Generate API keys securely (rotation requires contacting support — clicking "Generate API Key" again returns the existing key)
  • Log calls against existing leads via a sibling /calls endpoint — useful when your dialer or CRM logs the outcome of a call and you want Kraya to record it on the lead's call timeline (and optionally fire call_logged Smart Trigger rules)

How it works (user-facing)

  1. Generate API credentials: In the Dashboard, navigate to the Connect Kraya (API) page and click "Generate API Key". You'll receive:

    • A unique slug (8 random characters) used in the API endpoint URL
    • An api_key (16 random characters) used in the request header for authentication
    • A default_country_code (defaults to "91" for India) for phone number normalization

  2. Make API requests: Send POST requests to https://kraya-ai.com/api/external/{slug}/leads with:

    • Header: X-KRAYA-API-KEY: <your_api_key>
    • Header: Content-Type: application/json
    • Body: JSON with lead data (name, phone, email, notes, pipeline, stage, sequence, custom attributes)

  3. Lead upsert logic:

    • The API finds existing leads by phone number (normalized with country code)
    • If a lead exists: Updates the lead with new data
    • If no lead exists: Creates a new lead
    • Phone normalization: Phone numbers are normalized using the default country code if no country code is present

  4. Pipeline and stage assignment:

    • If both pipeline and stage are provided and valid, the lead is moved to that pipeline/stage
    • If not provided, new leads default to "Leads" pipeline and "New Lead" stage
    • Pipeline and stage names must match an existing name (matching is case-insensitive; the stage must belong to the pipeline)

  5. Sequence assignment:

    • If sequence is provided and matches an active sequence name, it's assigned to the lead
    • Sequence assignment initializes the sequence timing and sets the next message
    • If the sequence is already assigned, it updates the sequence assignment

  6. Custom attributes:

    • Only attributes that match your organization's default attributes are accepted
    • Attributes not in your default attributes list are ignored
    • Existing attribute values are merged with new values (new values override existing)

  7. Response: Returns JSON with lead_id and a success message indicating whether the lead was created or updated

Prerequisites & basics

  • Access to the Kraya Dashboard
  • Organization admin or appropriate permissions to generate API keys
  • An external system capable of making HTTP POST requests
  • Understanding of your organization's pipeline names, stage names, and sequence names (must match exactly)

Step-by-step guide

  1. Generate API Key

    • Navigate to https://kraya-ai.com/dashboard/api in your Kraya Dashboard
    • Click "Generate API Key" button
    • Copy and securely store both the slug and api_key
    • Note: If an API key already exists, clicking "Generate" will return the existing key (it doesn't regenerate)

  2. Configure default country code (optional)

    • On the same page, set your default country code (e.g., "91" for India, "1" for US)
    • This is used to normalize phone numbers that don't include a country code
    • Default is "91" (India)

  3. Test the API

    • Use curl, Postman, or your preferred HTTP client to send a test request
    • Verify the response includes a lead_id and success message

  4. Integrate with your system

    • Store the API key securely (never expose it client-side)
    • Implement error handling for various response codes
    • Set up retry logic for transient failures

API Endpoint Details

Endpoint: POST https://kraya-ai.com/api/external/{slug}/leads

Headers:

  • X-KRAYA-API-KEY (required): Your API key
  • Content-Type (required): application/json

Request Body Fields:

  • name (string, required): Lead's name
  • phone (string, required): Phone number (with or without country code; will be normalized)
  • email (string, optional): Valid email address
  • notes (string, optional): Lead notes
  • pipeline (string, optional): Pipeline name (must match exactly; required if stage is provided)
  • stage (string, optional): Stage name within the pipeline (must match exactly; required if pipeline is provided)
  • sequence (string, optional): Auto Followup sequence name (must match an active sequence exactly)
  • Custom attributes: Any additional fields whose key matches one of your organization's default attributes exactly, including case (attribute-name matching via the API is case-sensitive — City ≠ city)

Response Format:

{
  "lead_id": "uuid-string",
  "message": "Lead created successfully" // or "Lead updated successfully"
}

Error Responses:

  • 400 Bad Request: Validation errors (e.g., missing required fields, invalid email, pipeline/stage not found)
  • 401 Unauthorized: Invalid API key
  • 404 Not Found: Invalid slug (webhook URL)
  • 500 Internal Server Error: Server error processing the request

Logging calls against a lead

A sibling endpoint lets the same integration log a phone call against an existing lead. Useful when your dialer or CRM records call outcomes (status, duration, notes, transcript) and you want Kraya to mirror them on the lead's call timeline — and optionally trigger call_logged Smart Trigger rules.

Endpoint: POST https://kraya-ai.com/api/external/{slug}/calls

Headers (identical to the /leads endpoint):

  • X-KRAYA-API-KEY (required): Your API key
  • Content-Type (required): application/json

Two modes: the endpoint either creates a new call entry or updates an existing one, depending on whether call_id is in the body.

Create a new call entry

Provide either lead_id or phone to identify the lead. Kraya never creates a lead from this endpoint — if the lead can't be matched within your organization, the call returns 404.

Request Body Fields:

  • lead_id (integer, required if phone is not provided): The Kraya lead ID
  • phone (string, required if lead_id is not provided): Phone number (with or without country code; normalized against your default country code)
  • call_status (string, required): One of done or no_response
  • call_duration (integer, required): Call duration in seconds (0 is valid for no_response)
  • call_name (string, optional): A short label for the call (e.g. "Welcome call", "Discovery call")
  • call_notes (string, optional): Free-form notes, up to 5,000 characters

Response Format (200 OK):

{
  "call_id": 12345,
  "lead_id": 678901,
  "message": "Call logged successfully"
}

The returned call_id is what you'd send back later to update this same call entry.

Update an existing call entry

Provide the call_id you received when you first logged the call. Any of the loggable fields can be updated.

Request Body Fields:

  • call_id (integer, required): The Kraya call ID returned by the create call
  • call_name (string, optional): Update the label
  • call_notes (string, optional): Update the notes
  • call_status (string, optional): Update the status — still restricted to done or no_response
  • call_duration (integer, optional): Update the duration in seconds

Only the fields you send are updated; everything else is preserved.

Response Format (200 OK):

{
  "call_id": 12345,
  "lead_id": 678901,
  "message": "Call updated successfully"
}

Error Responses (same shape as the /leads endpoint):

  • 400 Bad Request: Validation errors (e.g., missing both lead_id and phone on create, invalid call_status, negative call_duration)
  • 401 Unauthorized: Invalid API key
  • 404 Not Found: Invalid slug (webhook URL); lead not found in your organization; call_id not found or belongs to another organization
  • 500 Internal Server Error: Server error processing the request

Limits & behavior (calls endpoint)

  • Match-or-404 only: This endpoint matches an existing lead by lead_id or phone. It never creates a lead. If you need to create a lead first, call the /leads endpoint and use the returned lead_id for the call.
  • Call source: Calls logged through this endpoint are tagged external-api (visible internally on the call entry).
  • call_status is restricted to done or no_response. Any other value returns 400.
  • completed flag is derived from call_status (done → completed, no_response → not completed). You don't set it directly.
  • Smart Trigger rules: call_logged rules fire automatically when a call is created through this endpoint (provided the status is done or no_response). Rules do not re-fire when you update a call — only the initial create dispatches them. Plan accordingly: send call_status correctly on the first call, or accept that subsequent corrections won't re-trigger automation.
  • Phone normalization follows the same rules as the /leads endpoint (default country code applied if missing; both normalized and non-normalized formats checked to prevent missed matches).

Limits & behavior

  • Phone deduplication: Leads are matched by phone number (normalized). If a lead with the same phone exists, it's updated; otherwise, a new lead is created.
  • Phone normalization:
    • Phone numbers are normalized using the default country code if no country code is present
    • The system checks both normalized and non-normalized phone numbers to prevent duplicates
    • Invalid phone numbers return a 400 error
  • Pipeline/Stage validation:
    • Pipeline and stage names must match an existing name (matching is case-insensitive; the stage must belong to the pipeline)
    • Both must be provided together (you can't provide one without the other)
    • Pipeline must exist in your organization
    • Stage must exist in the specified pipeline and must not be a default stage (is_default: false)
  • Sequence validation:
    • Sequence name must match an active sequence (matching is case-insensitive)
    • Sequence must be active (not deleted or deactivated)
    • If sequence is not found, returns 404 error
  • Custom attributes:
    • Only attributes that exist in your organization's default attributes are accepted
    • Attributes not in default attributes are silently ignored
    • Existing attribute values are merged with new values
  • Notes handling:
    • If notes is provided, it replaces any existing notes (not appended)
    • If notes is not provided, existing notes are preserved
  • Email validation:
    • Email must be a valid email format if provided
    • Invalid email format returns a 400 error
  • API key security:
    • API keys are encrypted at rest using KMS
    • API key comparison uses secure hash comparison to prevent timing attacks
    • Never expose API keys in client-side code or public repositories

Common edge cases and how to handle them

  • Duplicate leads with different phone formats

    • The system normalizes phone numbers and checks both normalized and non-normalized formats
    • Use consistent phone formatting (with country code recommended) to avoid duplicates
    • If you see duplicates, check if phone numbers differ only in formatting

  • Pipeline/Stage not found

    • Verify pipeline and stage names match an existing name (matching is case-insensitive, but spaces and spelling must match)
    • Ensure the stage is not a default stage (default stages cannot be assigned via API)
    • Check that the pipeline exists in your organization

  • Sequence not found

    • Verify the sequence name matches an active sequence (matching is case-insensitive)
    • Ensure the sequence is active (not deleted or deactivated)
    • Check that the sequence exists in your organization

  • Custom attributes not saving

    • Only attributes that exist in your organization's default attributes are accepted
    • Check your default attributes in the Dashboard to see which attributes are available
    • Attributes not in default attributes are silently ignored (no error returned)

  • Phone number normalization issues

    • If phone numbers aren't normalizing correctly, check your default country code setting
    • Phone numbers with country codes are normalized correctly
    • Phone numbers without country codes use the default country code

  • Existing lead not updating

    • Verify the phone number matches exactly (after normalization)
    • Check that you're using the correct organization's API key
    • Ensure the lead exists in the same organization

Troubleshooting

401 Unauthorized / Invalid api key

  • Verify the X-KRAYA-API-KEY header name is correct (case-sensitive)
  • Check that the API key value matches exactly (no extra spaces or characters)
  • Ensure you're using the API key from the correct organization
  • If you suspect the key has been compromised and want to rotate it, contact support — clicking "Generate API Key" again returns the existing key, it does not regenerate

404 Not Found / Invalid webhook URL

  • Verify the slug in the URL matches your API key's slug exactly
  • Check that the endpoint URL is correct: /api/external/{slug}/leads
  • Ensure the slug hasn't changed (slugs don't change unless support rotates the key)

400 Bad Request / Validation errors

  • Check that name and phone are provided and are strings
  • Verify email is a valid email format if provided
  • Ensure pipeline and stage are provided together and match exactly
  • Verify sequence name matches an active sequence exactly
  • Check that phone number is valid and can be normalized

Lead not created/updated

  • Verify all required fields (name, phone) are present
  • Check that phone number can be normalized (valid format)
  • Ensure you're using the correct organization's API key
  • Check server logs if issue persists (contact support)

Pipeline/Stage didn't change

  • Verify pipeline name matches an existing pipeline (matching is case-insensitive)
  • Verify stage name matches an existing stage (matching is case-insensitive)
  • Ensure both pipeline and stage are provided together
  • Check that the stage is not a default stage
  • Verify the stage belongs to the specified pipeline

Sequence not assigned

  • Verify sequence name matches an active sequence (matching is case-insensitive)
  • Ensure the sequence is active (not deleted or deactivated)
  • Check that the sequence exists in your organization

Custom attributes not saving

  • Verify attribute names match your default attributes exactly, including case — via the API, attribute-name matching is case-sensitive (e.g., City will not match a city attribute). This is stricter than pipeline/stage names, which are case-insensitive. (The Google Sheets and CSV import flows match attribute names case-insensitively, but the API does not.)
  • Check your default attributes in the Dashboard
  • Attributes not in default attributes are silently ignored

Phone number normalization issues

  • Check your default country code setting in the Dashboard
  • Phone numbers with country codes are normalized correctly
  • Phone numbers without country codes use the default country code
  • Invalid phone numbers return a 400 error

FAQs

  • Can I rotate the API Key?

    • Yes, but note that clicking "Generate API Key" again returns the existing key (it doesn't regenerate). To rotate, you would need to contact support or use a different method. The slug remains the same when regenerating.

  • Does it support GET requests?

    • No. This endpoint only supports POST requests for creating/updating leads.

  • Can I retrieve lead data via API?

    • No. This API is write-only (create/update). To retrieve lead data, use the Kraya Dashboard or other Kraya features.

  • What happens if I send the same lead twice?

    • The API uses phone number for deduplication. If a lead with the same phone number exists, it's updated with the new data. If not, a new lead is created.

  • Can I update only specific fields?

    • Yes. You can send only the fields you want to update. However, note that notes replaces existing notes (doesn't append), and custom attributes are merged with existing values.

  • What is the default country code?

    • Default is "91" (India). You can change this in the Dashboard API settings page.

  • How are phone numbers normalized?

    • Phone numbers are normalized using the default country code if no country code is present. The system checks both normalized and non-normalized formats to prevent duplicates.

  • Can I assign a sequence to an existing lead?

    • Yes. If you send a sequence parameter in an update request, the sequence is assigned (or updated if already assigned).

  • What happens if pipeline/stage doesn't exist?

    • Returns a 400 error with message "Pipeline not found" or "Stage not found". The lead is not created/updated in this case.

  • What happens if sequence doesn't exist?

    • Returns a 404 error with message "Sequence not found". The lead is still created/updated, but without the sequence assignment.

  • Can I create custom attributes via API?

    • No. Custom attributes must be created in the Dashboard first. The API can only set values for attributes that already exist in your default attributes.

  • Are there rate limits?

    • Rate limits are not explicitly documented for end users. If you encounter rate limiting, contact support.

  • What is the response time?

    • Response time varies but is typically under 1 second for successful requests. Failed requests may take longer due to validation.
  • Auto Followups (sequences can be assigned via API)
  • Dashboard (for managing pipelines, stages, sequences, and default attributes)
  • Smart Triggers (may be triggered when leads are created/updated via API)
  • Webhooks (for receiving notifications when leads are created/updated)

Screenshots (to add later)

Webhooks

Receive real-time event notifications from Kraya into your own systems.

Other Integrations

Call tracking and additional integrations like MyOperator.

On this page

OverviewWhat you can doHow it works (user-facing)Prerequisites & basicsStep-by-step guideAPI Endpoint DetailsLogging calls against a leadCreate a new call entryUpdate an existing call entryLimits & behavior (calls endpoint)Limits & behaviorCommon edge cases and how to handle themTroubleshootingFAQsRelated featuresScreenshots (to add later)