PATCH
/
api
/
v1
/
leads
/
{leadId}
Update Lead
curl --request PATCH \
  --url https://app.journeybee.io/api/v1/leads/{leadId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "company_name": "<string>",
  "email": "<string>",
  "phone_number": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "status": "<string>",
  "assignedUsers": [
    {}
  ],
  "tags": [
    {}
  ],
  "customFields": [
    {
      "customFieldId": 123,
      "type": "<string>",
      "value": {}
    }
  ]
}'
{
  "id": 789,
  "uuid": "lead-uuid-789",
  "updated_at": "2024-01-15T14:30:00Z"
}

​
Authentication

curl -X PATCH "https://app.journeybee.io/api/v1/leads/{leadId}" \
  -H "Authorization: Bearer your-api-key-uuid" \
  -H "Content-Type: application/json" \
  -d '{"status": "contacted", "tags": [1, 2, 3]}'

​
Path Parameters

​
leadId
number
required
The unique identifier of the lead to update

​
Request Body Schema

​
company_name
string
Lead company name
​
email
string
Lead contact email address
​
phone_number
string
Lead contact phone number
​
first_name
string
Lead contact first name
​
last_name
string
Lead contact last name
​
status
string
Lead status. Options: new, contacted, qualified, converted, lost
​
assignedUsers
array
Array of user IDs to assign to this lead (replaces existing assignments)
​
tags
array
Array of tag IDs to assign to this lead (replaces existing tags)
​
customFields
array
Array of custom field values to update

​
Response Schema

​
id
number
The updated lead ID
​
uuid
string
The lead UUID
​
updated_at
string
Timestamp of when the lead was last updated

​
Example Request

curl -X PATCH "https://app.journeybee.io/api/v1/leads/789" \
  -H "Authorization: Bearer jb_api_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "qualified",
    "company_name": "TechCorp Solutions Inc",
    "phone_number": "+1-555-123-4567",
    "assignedUsers": [123, 456],
    "tags": [10, 11, 12],
    "customFields": [
      {
        "customFieldId": 5,
        "type": "number",
        "value": {
          "number": 150000
        }
      },
      {
        "customFieldId": 6,
        "type": "select",
        "value": {
          "select": 3
        }
      }
    ]
  }'

​
Example Response

{
  "id": 789,
  "uuid": "lead-uuid-789",
  "updated_at": "2024-01-15T14:30:00Z"
}

​
Error Responses

{
  "error": "Invalid API key or insufficient permissions"
}

{
  "error": "Write access required for this operation"
}

{
  "error": "Lead not found or not accessible"
}

​
Notes

  • Requires API key with write_access permission
  • Only provided fields are updated (selective updates)
  • Array fields (assignedUsers, tags) replace existing values
  • Custom field updates are validated against field definitions
  • Triggers webhook events for integrations