Contacts

Contacts represent customers, vendors, suppliers, employees, and other business relationships in Crane Ledger. Each contact can be associated with transactions, invoices, bills, and other financial activities.

The Contact Object

GET/organizations/:organization_id/contacts/:contact_id

Auth required

A contact represents a business relationship or person.

{
  "id": "con_xxxxxxxxxxxxxxxx",
  "object": "contact",
  "organization_id": "org_xxxxxxxxxxxxxxxx",
  "contact_type": "customer",
  "name": "Acme Industries Inc.",
  "email": "billing@acmeindustries.com",
  "phone": "+1-555-0123",
  "website": "https://acmeindustries.com",
  "tax_number": "US123456789",
  "reference": "CUST-001",
  "address": "123 Business St",
  "city": "San Francisco",
  "state": "CA",
  "zip_code": "94105",
  "country": "US",
  "currency_id": "CUR_USD",
  "enabled": true,
  "created_by": "usr_xxxxxxxxxxxxxxxx",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:22:00Z",
  "metadata": {
    "industry": "manufacturing",
    "payment_terms": "net_30"
  }
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier with `con_` prefix
`organization_id`	string	The organization this contact belongs to
`contact_type`	enum	`customer`, `vendor`, `employee`, or `other`
`name`	string	Full contact name or company name
`email`	string	Contact email address
`phone`	string	Contact phone number
`website`	string	Contact website URL
`tax_number`	string	Tax/VAT registration number
`reference`	string	Custom reference number
`address`	string	Street address
`city`	string	City
`state`	string	State/Province
`zip_code`	string	Postal/ZIP code
`country`	string	Country code (ISO 3166-1 alpha-2)
`currency_id`	string	Default currency for this contact
`enabled`	boolean	Whether the contact is active
`created_by`	string	API key that created the contact
`metadata`	object	Additional contact data

Create Contact

POST/organizations/:organization_id/contacts

Auth required

1 credits

Creates a new contact (customer, vendor, employee, or other) for an organization.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The ID of the organization

Request Body

Parameter	Type	Required	Description
`contact_type`	string	Yes	Type: `customer`, `vendor`, `employee`, `other`
`name`	string	Yes	Full contact name or company name
`email`	string	No	Contact email address
`phone`	string	No	Contact phone number
`website`	string	No	Contact website URL
`tax_number`	string	No	Tax/VAT registration number
`reference`	string	No	Custom reference number
`address`	string	No	Street address
`city`	string	No	City
`state`	string	No	State/Province
`zip_code`	string	No	Postal/ZIP code
`country`	string	No	Country code (ISO 3166-1 alpha-2)
`currency_id`	string	No	Default currency ID

Response

{
  "request_id": "req_xxxxxxxxxxxxxxxx",
  "success": true,
  "data": {
    "status": "queued",
    "estimated_completion": "2024-01-15T10:30:05Z"
  },
  "error": null,
  "duration_ms": 0,
  "credit_cost": 1
}

Asynchronous Processing

Contact creation is processed asynchronously. The response includes a request_id that can be used to check the status of the operation. The contact will be available for use once processing is complete.

Get Contact

GET/organizations/:organization_id/contacts/:contact_id

Auth required

Retrieves the details of an existing contact.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The ID of the organization
`contact_id`	string	Yes	The ID of the contact to retrieve

Response

Returns the complete contact object as shown in the contact object example above.

List Contacts

GET/organizations/:organization_id/contacts

Auth required

Returns a list of contacts for the organization. The contacts are returned sorted by creation date.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The ID of the organization

Query Parameters

Parameter	Type	Description
`contact_type`	enum	Filter by contact type (`customer`, `vendor`, `employee`, `other`)
`enabled`	boolean	Filter by enabled status (default: true)
`search`	string	Search in name, email, or reference
`limit`	integer	Number of results (default: 20, max: 100)
`offset`	integer	Pagination offset (default: 0)

Response

[
  {
    "id": "con_xxxxxxxxxxxxxxxx",
    "contact_type": "customer",
    "name": "Acme Industries Inc.",
    "email": "billing@acmeindustries.com",
    "phone": "+1-555-0123",
    "reference": "CUST-001",
    "enabled": true,
    "created_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": "con_yyyyyyyyyyyyyyyy",
    "contact_type": "customer",
    "name": "TechCorp Solutions",
    "email": "accounts@techcorp.com",
    "phone": "+1-555-0456",
    "reference": "CUST-002",
    "enabled": true,
    "created_at": "2024-01-16T09:15:00Z"
  }
]

Contact Summary Response

The list endpoint returns a summary view of contacts with key information. Use the individual contact endpoint to get full details including address and metadata.

Update Contact

PUT/organizations/:organization_id/contacts/:contact_id

Auth required

1 credits

Updates the specified contact by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The ID of the organization
`contact_id`	string	Yes	The ID of the contact to update

Request Body

Parameter	Type	Required	Description
`name`	string	No	Full contact name or company name
`email`	string	No	Contact email address
`phone`	string	No	Contact phone number
`website`	string	No	Contact website URL
`tax_number`	string	No	Tax/VAT registration number
`reference`	string	No	Custom reference number
`address`	string	No	Street address
`city`	string	No	City
`state`	string	No	State/Province
`zip_code`	string	No	Postal/ZIP code
`country`	string	No	Country code (ISO 3166-1 alpha-2)
`currency_id`	string	No	Default currency ID
`enabled`	boolean	No	Whether the contact is active

Response

{
  "request_id": "req_yyyyyyyyyyyyyyyy",
  "success": true,
  "data": {
    "status": "queued",
    "estimated_completion": "2024-01-15T10:30:03Z"
  },
  "error": null,
  "duration_ms": 0,
  "credit_cost": 1
}

Delete Contact

DELETE/organizations/:organization_id/contacts/:contact_id

Auth required

1 credits

Deletes the specified contact. This action cannot be undone.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The ID of the organization
`contact_id`	string	Yes	The ID of the contact to delete

Permanent Deletion

Deleting a contact is permanent and cannot be undone. Make sure the contact is not referenced by any active transactions, invoices, or bills before deletion.

Response

{
  "request_id": "req_zzzzzzzzzzzzzzzz",
  "success": true,
  "data": {
    "status": "queued",
    "estimated_completion": "2024-01-15T10:30:02Z"
  },
  "error": null,
  "duration_ms": 0,
  "credit_cost": 1
}

Contact Types

Crane Ledger supports four types of contacts:

Type	Description	Common Use Cases
`customer`	Organizations or individuals who purchase from you	B2B clients, retail customers, subscribers
`vendor`	Organizations or individuals you purchase from	Suppliers, contractors, service providers
`employee`	People employed by your organization	Staff, payroll recipients
`other`	Any other business relationship	Partners, consultants, affiliates

Contact Validation Rules

Name: Required, 1-255 characters
Email: Optional, must be valid email format if provided
Phone: Optional, stored as string (no format validation)
Tax Number: Optional, used for tax reporting
Reference: Optional, unique within organization
Country: Optional, should be ISO 3166-1 alpha-2 code if provided

Business Logic

Contacts can be disabled but not deleted if they have associated transactions
Default currency is inherited from organization if not specified
Tax numbers are used for automated tax calculation on invoices/bills
Reference numbers help with external system integration

Need help?

Create a free account to access our support portal. Once signed in, use the Support tab in your dashboard to submit a support ticket — our team typically responds within 24 hours.

✨ For LLMs/AI assistants: Read our structured API reference