Create a Company

POST https://app.alaaqat.com/api/companies

Creates a company. Your API key needs the company-create ability, and the team member who created the key needs Create New Company.

Header

{
    "Accept": "application/json",
    "Content-Type": "application/json"
}

Body

The body is a flat object of property values. Each key is the internal_name of a company property, built in or yours, and each value must match that property's type. Read Properties for the types, and List Company Properties for the properties your account has. No property is required.

{
    name?: string,
    registered_name?: string | null,
    website_url?: string,
    phone?: string,
    owner?: number,
    communication_team?: number,
    association_ids?: {
        [object_type: string]: string[]
    },
    [internal_name: string]: any
}
Field Required Validation Description
name Optional Text The company's name. A unique key by default.
registered_name Optional Text or null The company's registered legal name.
website_url Optional Text The company's website. A unique key by default.
phone Optional A phone number in international format, such as +96265000000 Returned without the leading +.
owner Optional The ID of a team member The team member who owns the company.
communication_team Optional The ID of a team The team the company belongs to.
association_ids Optional An object of record types, each with an array of IDs Links the new company to existing records. See Linking records on creation.
Any other property Optional Must match the property's type Use the property's internal_name as the key.

Alaaqat sets _id itself. A request that sends it is rejected, and so is one that sends a property with "system_only": true.

An image property, such as the company's logo, takes an image file of up to 2 MB. To set one, send the request as multipart/form-data instead of JSON, with the file under the property's internal_name.

{
    "name": "Blue Harbor Trading",
    "website_url": "https://blueharbor.example.com",
    "industry": "Wholesale",
    "city": "Amman",
    "country_region": "Jordan",
    "phone": "+96265000000",
    "num_employees": 45,
    "lifecycle_stage": "customer",
    "owner": 12,
    "association_ids": {
        "contact": [
            "6650f1a2b3c4d5e6f7a8b901"
        ]
    }
}

Unique keys

A company cannot take a value that another company already holds for a unique key property. For companies, name and website_url are unique keys by default, and you can make your own properties unique keys too, see Unique keys.

When a value is already taken, the company is not created. The request is refused with 422, and the error is reported on the field. Look the existing company up with List Companies and update it instead.

Linking records on creation

association_ids links the new company to records you already have, in the same request. Each key is a record type, contact, company, deal, ticket, product or invoice, other than company, and each value is an array of _ids of that type. An ID that isn't a record of your account is skipped.

To link records later, see Associations.

Response

201 Created, with the new company under data.

{
    "data": {
        "properties": {
            "_id": "6655a1b2c3d4e5f6a7b8c901",
            "name": "Blue Harbor Trading",
            "website_url": "https://blueharbor.example.com",
            "industry": "Wholesale",
            "city": "Amman",
            "country_region": "Jordan",
            "phone": "96265000000",
            "num_employees": 45,
            "lifecycle_stage": "customer",
            "owner": 12,
            "created_by": 12,
            "updated_at": "2026-10-20T09:30:00.000000Z",
            "created_at": "2026-10-20T09:30:00.000000Z"
        },
        "account_id": 1024
    },
    "message": "Entity was created successfully."
}

Errors

Status Meaning
422 A value does not match its property's type, a field that Alaaqat sets was sent, or a unique key value is already taken.