Create a Company Property

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

Creates a custom property for your companies. Your API key needs the company-property-create ability, and the team member who created the key needs Create Custom Field.

Read Properties for the available types and the format of the options of a single_select property.

Header

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

Body

{
    type: string,
    name: {
        en?: string,
        ar?: string
    },
    desc?: {
        en?: string,
        ar?: string
    },
    internal_name: string,
    group_id: string,
    enum?: [
        {
            en?: string,
            ar?: string,
            internal_name: string
        }
    ],
    is_unique_key?: boolean
}
Field Required Validation Description
type Required One of the property types The kind of value the property holds. It cannot be changed later.
name Required An object with at least one language, each value text The property name, in en, ar or both.
desc Optional An object of languages, each value text or null A description, in en, ar or both.
internal_name Required Letters, digits and underscores only. It cannot start with alaaqat, and no other company property, built in or yours, may already use it. The key that holds the property's value on a company. It cannot be changed later.
group_id Required The _id of a company property group, built in or yours The group the property is listed under. See List Company Property Groups.
enum Optional An array of options, each with an internal_name that is unique within the array The options of a single_select property. Leave it out for other types.
is_unique_key Optional true or false Makes the property a unique key. See Unique keys below.

Alaaqat fills in account_id and made_by itself. A request that sends either one is rejected.

A text property that works as a unique key:

{
    "type": "string",
    "name": {
        "en": "Tax number",
        "ar": "الرقم الضريبي"
    },
    "desc": {
        "en": "The tax registration number of the company",
        "ar": "رقم التسجيل الضريبي للشركة"
    },
    "internal_name": "tax_number",
    "group_id": "6653c0d1e2f3a4b5c6d7e821",
    "is_unique_key": true
}

A single_select property:

{
    "type": "single_select",
    "name": {
        "en": "Customer tier",
        "ar": "فئة العميل"
    },
    "internal_name": "customer_tier",
    "group_id": "6653c0d1e2f3a4b5c6d7e821",
    "enum": [
        {
            "en": "Gold",
            "ar": "ذهبية",
            "internal_name": "gold"
        },
        {
            "en": "Silver",
            "ar": "فضية",
            "internal_name": "silver"
        },
        {
            "en": "Bronze",
            "ar": "برونزية",
            "internal_name": "bronze"
        }
    ]
}

Unique keys

A unique key stops two companies from holding the same value for the property:

  • Creating or updating a company with a value that another company already holds is refused with 422, and the error is reported on that field.
  • Turning the unique key on is refused with 422 while two or more companies already share a value for the property. Resolve those duplicates first, then turn it on.

For companies, name and website_url are unique keys by default. To allow duplicates in one of them, update the property with "is_unique_key": false.

Response

201 Created, with the new property under data.

{
    "data": {
        "type": "string",
        "name": {
            "en": "Tax number",
            "ar": "الرقم الضريبي"
        },
        "desc": {
            "en": "The tax registration number of the company",
            "ar": "رقم التسجيل الضريبي للشركة"
        },
        "internal_name": "tax_number",
        "group_id": "6653c0d1e2f3a4b5c6d7e821",
        "is_unique_key": true,
        "account_id": 1024,
        "made_by": 12,
        "updated_at": "2026-10-20T09:15:00.000000Z",
        "created_at": "2026-10-20T09:15:00.000000Z",
        "_id": "6654d0e1f2a3b4c5d6e7f811",
        "user": {
            "id": 12,
            "email": "sara.haddad@example.com",
            "firstname": "Sara",
            "lastname": "Haddad",
            "image": null,
            "locale": "en",
            "created_at": "2026-03-02T08:00:00.000000Z",
            "updated_at": "2026-10-01T07:30:00.000000Z",
            "fullname": "Sara Haddad"
        },
        "group": {
            "_id": "6653c0d1e2f3a4b5c6d7e821",
            "internal_name": "company_information",
            "name": {
                "en": "Company Information",
                "ar": "معلومات الشركة"
            },
            "desc": [],
            "account_id": null,
            "made_by": null,
            "updated_at": "2026-01-10T00:00:00.000000Z",
            "created_at": "2026-01-10T00:00:00.000000Z"
        }
    },
    "message": "Entity was created successfully."
}

Errors

Status Meaning
402 Your plan's limit of custom properties is reached. See the plans on the pricing page.
422 A field failed validation. For example, the internal name is already used or contains other characters, the group does not exist, or is_unique_key is true while companies already share a value.