Skip to content
Levr API Documentation
Download OpenAPI specOpenAPI

Hand off to an AI agent

Copy instructions to your AI agent

Copy this guide into your AI agent. It links to the current REST API and MCP documentation.

You are helping someone integrate their system with Levr. Use Levr's published documentation and machine-readable contracts as the source of truth. Do not invent endpoints, fields, or MCP tools.

  1. Start with the Levr API documentation to choose between a server-to-server REST integration and a user-authorized MCP connection.
  2. For REST, read the Markdown REST API guide, choose the user’s task, then fetch only the relevant resource guide and operation Markdown. Resource indexes include task guidance. For funding recommendations, start with the Matchmaking guide. Use the OpenAPI specification for exact paths, authentication, parameters, and envelope schemas.
  3. For REST client intake, Deal applications, or project Criteria, fetch that resource's contract_url. Its Application Contract is the authority for the current questions, stable keys, repeatable groups, file-transfer steps, accepted answer shapes, conditional visibility, supported operation URLs, and integration instructions. Repeatable fields require the returned item_id. File bytes use the expiring upload_url and multipart field named file; they never belong in JSON. Do not substitute a static example or the latest application definition.
  4. For an AI client acting with a signed-in user's access, read the MCP connection instructions in Markdown first, then the Model Context Protocol guide if needed. Let the connected MCP server expose its current tools and input contracts; do not infer tools from the REST API. Read the relevant MCP resource guide and follow the discovered tool’s revision, file-transfer, and confirmation requirements.
  5. Use URLs from the record handoff when supplied; otherwise use this documentation environment. Keep API keys and file-transfer credentials out of browser code, logs, prompts, and source control.
  6. Before implementing a write, verify authentication, required inputs, idempotency, error responses, and retry guidance in the current contract. If an operation is not documented, do not assume it exists.

Early access

Request an integration

Tell us what your integration needs to do. Add an email if you want a reply.

Business guides

Create a business profile

Read as Markdown

Create a business and its primary contact in the receiving Portal through the API. Use this flow to transfer business records from an internal system or an external referrer's integration.

The result: the request creates a business profile with contact details. It does not start an intake form, Deal application, or funding request. The example suppresses client invitations.

This is the baseline for every starting experience. Add intake, a Deal, or matchmaking when needed using the follow-up calls below; you do not need to move the business to a different source.

1. Prepare the source

A Lead source chooses how incoming businesses get started. The API calls it a source channel; pass its ID as source_channel_id when creating a business. Its settings determine whether business creation also starts an application. Application answers are always saved separately.

The receiving Portal is the workspace associated with your API key. Ask its administrator or your integration contact for:

  • An API source ID (srcch_…) configured as Business profile only, plus a link to that source in the Portal.
  • Your environment’s API origin and a Portal API key scoped to the source with lead_submissions:write and businesses:read.
  • Confirmation that the source is ready and the Portal has a default business pipeline and stage. No published application is needed.
Configure the source if you have Portal access

With permission to manage the source, open the Lead source, then Overview → Getting started → Change setup, and choose Business profile only. For a new source, choose API integration when creating it.

The source’s API setup section contains its ID and integration instructions. If a choice is locked, follow the restriction message and contact your administrator. A source-scoped key can also discover its IDs through the API root.

Create the source through the API instead

With source_channels:write, POST the following body to /v1/source-channels/ with your bearer key and a new Idempotency-Key. Use the returned id as source_channel_id when creating the business. Read GET /v1/source-channels/{id}/ to confirm the source’s current setup and readiness.

{
  "name": "Website enquiries",
  "starting_experience": "business_profile"
}

starting_experience is required when creating a source. To find an existing source, use List Lead sources with source_channels:read.

2. Check the source setup

Use your environment's API origin and a server-side bearer key; Get started explains authentication. All requests below include Authorization: Bearer <API_KEY>. JSON writes also include Content-Type: application/json and a unique Idempotency-Key. Retain each write's key and body for retries.

Examples use illustrative IDs. Responses show only the fields needed for the next step; use the actual IDs and URLs returned by your API.

Request

GET /v1/source-channels/srcch_example/

Response · selected fields

{
  "starting_experience": "business_profile",
  "readiness": { "is_ready": true }
}

Confirm starting_experience is business_profile and readiness.is_ready is true. If the setup differs, confirm the source with the receiving Portal's administrator before creating records.

3. Create the business

Business creation uses the same payload structure for every starting experience. Send the source ID and contact details:

POST /v1/businesses/
Idempotency-Key: website-lead-12345-business
{
  "source_channel_id": "srcch_REPLACE_ME",
  "business": {
    "name": "Cedar Ridge Engineering Ltd.",
    "primary_contact_name": "Maya Chen",
    "primary_contact_email": "maya@example.com",
    "primary_contact_phone": "+16045550123"
  },
  "invite_client": false
}

An existing email address can reuse a contact within your key’s permitted scope. Creating a business does not overwrite that contact’s saved details.

invite_client: false suppresses the invitation. true sends it during creation; omission or null follows the source's invitation setting. To invite later, keep it false and arrange the invitation through the receiving team’s Portal afterward.

Response · 201, selected fields

{
  "business": {
    "id": "biz_example",
    "url": "https://YOUR_API_HOST/v1/businesses/biz_example/"
  },
  "starting_experience": "business_profile",
  "client_intake_application": null,
  "deal": null,
  "deal_application": null
}

Save business.id before continuing. An identical retry returns the original result; a new key can create another business. Application answers belong in later requests. If returned, invitation_url is a private client access link.

4. Verify the created business

The response's business.id identifies the new record; business.url is its API URL, not a Portal link. client_intake_application and deal_application are null; no Deal is created by this flow.

Read the returned business.url to confirm the saved record:

GET /v1/businesses/biz_example/

If you have access to the receiving Portal, open Businesses, find Cedar Ridge Engineering Ltd., and check the business and primary contact details. It should be in the receiving Portal’s default business pipeline and stage. Without Portal access, ask the receiving team to confirm the contact details.

You've finished when the saved business has the intended contact details and no unexpected invitation was sent. The receiving team can now work with the business record.

Continue from the baseline

The source records where the business came from and chooses what is created alongside it. You can add other applications and funding goals later. Each action requires the relevant API permissions, access to the business, and any Portal features listed below.

Add client intake

With client_intake_applications:write, create the intake with no request body:

POST /v1/businesses/biz_example/client-intake/
Idempotency-Key: website-lead-12345-intake

Response · selected fields

{
  "business_id": "biz_example",
  "application_id": "ciappl_example",
  "created": true,
  "client_intake_application": {
    "id": "ciappl_example",
    "url": "https://YOUR_API_HOST/v1/client-intake-applications/ciappl_example/",
    "contract_url": "https://YOUR_API_HOST/v1/client-intake-applications/ciappl_example/contract/",
    "answers_url": "https://YOUR_API_HOST/v1/client-intake-applications/ciappl_example/answers/"
  }
}

This uses the source's published intake template. Automatic intake creation can remain disabled; the business must have originated through the receiving Portal. If intake already exists, the endpoint returns it with created: false instead of creating another form.

Continue with Complete and submit a client intake, using the returned client_intake_application ID and URLs. Complete and submit this intake in the same way as one created automatically with the business.

Start a Deal application

With deal_recipients:read, read the available recipients:

GET /v1/deal-recipients/?business_id=biz_example

Choose the receiving Portal's recipient with can_create_deal: true to start an application to that Portal. With deals:write, use its returned ID:

POST /v1/deals/
Idempotency-Key: website-lead-12345-deal
{
  "business_id": "biz_example",
  "recipient_id": "<recipient-id-from-discovery>"
}

Response · selected fields

{
  "id": "deal_example",
  "application": { "id": "dapp_example" }
}

When applying to the receiving Portal, the Deal uses the source's configured application, or the Portal's default published application if none is configured. This is the same form you would get from the Deal application starting experience.

Continue with Complete and submit a Deal, using application.id and deal_applications:write. Recipient discovery also lets you choose another available recipient when the business is ready to apply elsewhere.

Create a project

With projects:write, create a project to track a funding goal:

POST /v1/projects/
Idempotency-Key: website-lead-12345-project
{
  "business_id": "biz_example",
  "name": "Equipment expansion",
  "target_amount": "250000",
  "target_currency": "CAD"
}

Save the returned Project id. You can complete Criteria and find funding recommendations with the permissions and Portal setup listed in that guide. Client matchmaking does not need to be enabled to run matching for your team.

Enable the client's matchmaking experience

Let the client use matchmaking, just as a self-serve matchmaking source would do during business creation. With businesses:read, read the current setting and retain its ETag:

GET /v1/businesses/biz_example/client-matchmaking/

Response · selected fields

{
  "business_id": "biz_example",
  "enabled": false,
  "available": false,
  "revision": "<current-revision>"
}

enabled records whether you have allowed client matchmaking for this business. available tells you whether the client can use it; the Portal must also support client matchmaking. With businesses:write, enable it using the returned ETag:

PATCH /v1/businesses/biz_example/client-matchmaking/
If-Match: "<current-revision>"
Idempotency-Key: website-lead-12345-client-matchmaking
{ "enabled": true }

This allows client matchmaking for the business. It does not create a project or funding request, or send an invitation. The business must have an active, approved relationship with the receiving Portal. On 412, read the setting again and confirm your intended change before retrying.

To include the client in a funding goal, create a Project with a linked funding request. If you already created the project above, add its funding request without duplicating the Project:

GET /v1/projects/proj_example/

Use the Project response's ETag for the next request. No request body is needed:

POST /v1/projects/proj_example/funding-request/
If-Match: "<project-revision>"
Idempotency-Key: website-lead-12345-project-funding-request

The returned Project includes its linked service_request_id: 201 means the request was created, and 200 means the Project already had one. The client and your team use the same Criteria and matching work; private Project notes remain private. This requires projects:write, enabled client matchmaking, an active relationship with the Portal where the business originated, and the Portal's funding-request capability. It sends no invitation.

If a step fails

ResponseNext action
401, 403, or record not foundCheck the environment, ID, key permissions, and source scope.
409 source_channel_not_readyAsk the administrator to resolve the reported source setup problem, then read the source again.
409 on a retryCheck whether the body or precondition changed. Reuse a key only for the identical command.
Validation errorCorrect the named business or contact field against the creation schema.

After a connection failure, retry the same endpoint with the same key and body; the operation may already have succeeded. Keep the returned business ID so later work continues on the same business.