Create a Deal

POST/deals/

Start a Deal for an existing Business and a recipient, including your own Portal or a custom email recipient. Choose an id from List Deal recipients. Or use recipient.id from a matchmaking result. Uses the recipient's current published application and your default Deal pipeline. Creation keeps the application private to your team, starts Autofill, and does not submit it. Include project_id to link an in-scope Project belonging to this Business. Deals Write is sufficient; it does not grant later Project edits. An identical retry with the same Idempotency-Key returns the original Deal.

Required permissions: deals:write
Available scopes: Entire Portal or Selected source channels

Headers and URL parameters

Name	Location	Type	Required
`Idempotency-Key` View parameter schema	header	string	Yes

Request body

application/json · Required body

Field	Type	Required
`business_id`	string	Yes
`project_id`	string	No
`recipient_id`Recipient id returned by List Deal recipients or recipient.id from matchmaking.	string	Yes

View request schema

Example request

curl --request POST \
  --url "https://api.staging.levr.ai/v1/deals/" \
  --header "Authorization: Bearer $LEVR_API_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data "@request.json"

curl --request POST \
  --url "https://api.staging.levr.ai/v1/deals/" \
  --header "Authorization: Bearer $LEVR_API_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "business_id": "biz_2m8q7c9k4x6p3n5d",
  "recipient_id": "northstar-finance"
}'

Responses

Status	What it means
`201`	Successful response. View response headers `application/json` View response schema Illustrative data. Use the identifiers, cursors, and URLs returned by your requests. View example response
`400`	Correct the request fields and try again. View response headers `application/json` View response schema Illustrative data. Use the identifiers, cursors, and URLs returned by your requests. View example response
`401`	Provide a valid API key and try again. View response headers `application/json` View response schema Illustrative data. Use the identifiers, cursors, and URLs returned by your requests. View example response
`403`	This API key does not allow the requested action. View response headers `application/json` View response schema Illustrative data. Use the identifiers, cursors, and URLs returned by your requests. View example response
`404`	The requested resource was not found or is not available to this API key. View response headers `application/json` View response schema Illustrative data. Use the identifiers, cursors, and URLs returned by your requests. View example response
`409`	The request conflicts with the resource's current state. Refresh it before trying again. View response headers `application/json` View response schema Illustrative data. Use the identifiers, cursors, and URLs returned by your requests. View example response
`412`	The request was not completed. View response headers `application/json` View response schema Illustrative data. Use the identifiers, cursors, and URLs returned by your requests. View example response
`429`	Too many requests were sent. Wait before trying again. View response headers `application/json` View response schema Illustrative data. Use the identifiers, cursors, and URLs returned by your requests. View example response
`500`	Levr could not complete the request. Keep the request ID and retry when safe. View response headers `application/json` View response schema Illustrative data. Use the identifiers, cursors, and URLs returned by your requests. View example response

Copy instructions to your AI agent

Request an integration