Lead Intake API

Authentication

coreCRM uses a bearer API key. The key identifies your coreCRM account, so every record it creates lands in that account and nowhere else.

Getting a key

An admin on the coreCRM account creates it. Sign in, then open Settings and choose API Keys.

Fill in a Name so you can recognise the key later, and the App that will use it, then press Create Key.

Sending the key

Pass it as a bearer token. There is no query-parameter or request-body alternative.

Authorization: Bearer cl_YOUR_KEY_HERE

Rotating and revoking

Keys have no expiry, so rotation is manual. It can be done with no downtime:

1. Create a second key on the same screen.
2. Deploy the new key to your system.
3. Wait for the Last Used column on the new key to move. It updates on every accepted request.
4. Press Revoke on the old key.

Revoking takes effect immediately. Revoked keys stay listed so you keep the audit trail, and Delete removes the record entirely. Neither touches any Deal, Company, or Contact the key created. A revoked key returns exactly the same response as a key that never existed, so your error handling does not need to tell the two apart.

Request headers

Create a Lead

Request fields

pipeline_id, title, and company.name are the only required fields. The whole contact object is optional; omit it and the Deal is created against the Company with no Contact attached.

Fields coreCRM sets for you

These cannot be supplied by the caller. Sending them does nothing: they are ignored without an error.

If you need any of these three set from your side, that is a change to coreCRM rather than something you can configure. Talk to us.

Example request

Replace pipeline_id with a real pipeline from your account and cl_YOUR_KEY_HERE with your key. Everything else can be sent as-is.

curl -X POST https://corecrm.guru/api/v1/deals \
  -H "Authorization: Bearer cl_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "pipeline_id": 3,
    "title": "Roof replacement - Vega Roofing",
    "value": 12500,
    "contact": {
      "name": "Dana Vega",
      "email": "[email protected]",
      "phone": "(555) 0142"
    },
    "company": {
      "name": "Vega Roofing",
      "website": "https://example.com",
      "address": "400 Harbour Way",
      "city": "Tampa",
      "state": "FL",
      "zip": "33602",
      "industry": "Construction"
    },
    "metadata": {
      "campaign": "spring-roofing",
      "external_id": "LEAD-90210"
    }
  }'

Success response

{
  "id": 4812,
  "url": "https://corecrm.guru/app/deals/4812",
  "pipeline": "Inbound Leads",
  "stage": "New Lead"
}

The response deliberately contains no Contact or Company details.

Duplicate handling

Read this before you go live. The three records behave differently.

A Contact with no email is never matched. Omit contact.email and coreCRM creates a fresh Contact on every request, because email is the only key it matches on. Send the email whenever you have it.

Errors

Every error returns JSON. You do not need to send any particular Accept header to get it.

{
  "error": "API key required"
}

{
  "error": "Invalid API key"
}

{
  "message": "The title field is required.",
  "errors": {
    "title": ["The title field is required."]
  }
}

{
  "message": "The pipeline id field is required. (and 2 more errors)",
  "errors": {
    "pipeline_id": ["The pipeline id field is required."],
    "title": ["The title field is required."],
    "company.name": ["The company.name field is required."]
  }
}

{
  "message": "The route api/v1/leads could not be found."
}

{
  "message": "The PUT method is not supported for route api/v1/deals. Supported methods: POST."
}

{
  "error": "Rate limit exceeded",
  "retry_after": 37
}

{
  "error": "Failed to create deal",
  "message": "..."
}

Rate limits

The limit is per API key, counted per minute, and defaults to 60 requests per minute. The exact figure for a key is shown in the Rate Limit column on the API Keys screen.

Every response, successful ones included, carries:

Watch X-RateLimit-Remaining and slow down before you hit zero. If you need to import in bulk, spread the calls out rather than requesting a higher limit. The limit is set by corePHP and is not tenant-configurable.

Helper endpoints

Two read endpoints support the integration. Both take the same bearer key.

Find your pipeline and stage IDs

{
  "data": [
    {
      "id": 3,
      "name": "Inbound Leads",
      "is_default": true,
      "stages": [
        { "id": 11, "name": "New Lead",  "position": 1, "probability": 10, "color": "#94a3b8" },
        { "id": 12, "name": "Contacted", "position": 2, "probability": 25, "color": "#60a5fa" }
      ]
    }
  ]
}

Only pipelines in your own account are returned. IDs are stable, so fetch them once at setup rather than before every Lead.

Check a key works

{
  "tenant": "Acme Home Services",
  "tenant_id": 42
}

This creates nothing, so it is the safest way to confirm a key is live and pointed at the right account. Use it as your integration's health check.

Testing safely

Test like this instead:

1. Call GET /me first. It writes nothing and proves the key and account are right. Most credential mistakes are caught here.
2. Create a throwaway pipeline in coreCRM, called something like API Test, and point pipeline_id at it while you build. Test Leads stay out of the pipelines your reps actually watch.
3. Tag your test traffic with something you can search for later, for example "metadata": { "external_id": "TEST-001" }.
4. Delete the test Deals when you are finished, and switch pipeline_id to the real pipeline as the last step of going live.

Exercise your error handling with deliberately broken requests. They are free, because a request that fails never creates anything.

# Expect 401 {"error":"Invalid API key"}
curl -X POST https://corecrm.guru/api/v1/deals \
  -H "Authorization: Bearer cl_definitely_not_a_real_key" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"pipeline_id":3,"title":"t","company":{"name":"c"}}'

# Expect 422, errors.title
curl -X POST https://corecrm.guru/api/v1/deals \
  -H "Authorization: Bearer cl_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"pipeline_id":3,"company":{"name":"Vega Roofing"}}'

Integration checklist

• Key created in coreCRM and stored as a secret, not committed to source control.
• GET /me returns the expected account name.
• pipeline_id read from GET /pipelines, not hardcoded from a guess.
• Authorization and Content-Type sent on every request.
• contact.email sent whenever available, so Contacts deduplicate.
• Your own identifier sent in metadata.external_id.
• Retries deduplicated on your side, because the endpoint is not idempotent.
• 401, 422 and 429 each handled distinctly. Retry 429 after retry_after; never retry 422 unchanged.
• X-RateLimit-Remaining monitored.
• Test Deals deleted and pipeline_id switched to the live pipeline.

Scope and support

Version 1 writes Leads only. There is currently no public API to list, search, or update Leads, and none for any other object. If you need to read Leads back, tell us so it can be scoped properly.

For help, send the request timestamp, the payload you sent (minus the key), and the full response body including the status code.