NatiqDocs

Appearance

Open Natiq

Organisation

Read and update your organisation and brand, and manage users, invitations and roles.

Updated 7 Nov 2026

Your organisation is the account everything else belongs to. These endpoints read and change its profile and brand, and manage the people in it: who is a member, who has been invited, and which roles exist.

Access to people and roles is controlled by two permissions: admin:read to see them and admin:write to change them. Organisation-wide settings use org:read and org:write.

Endpoints

GET/orgRetrieve your organisationPATCH/orgUpdate your organisationGET/org/brandingRetrieve the brandPUT/org/brandingUpdate the brandPOST/org/branding/assetsUpload a brand imageGET/admin/usersList usersPOST/admin/users/inviteInvite a userGET/admin/invitationsList invitationsGET/admin/rolesList roles

The organisation object

Attributes

  • idinteger
    Unique identifier of your organisation. It is also the orgId in your sign-in response.
  • namestring
    Organisation name.
  • statusstring
    Account status, e.g. ACTIVE.
  • planstringnullable
    The plan the organisation is on.
  • countrystringnullable
    Country of the organisation.
  • createdAtstring
    When the organisation was created (ISO 8601).
  • updatedAtstring
    When it was last changed.
The organisation object
json
{
  "id": 12,
  "name": "Al-Noor Telecom",
  "status": "ACTIVE",
  "plan": null,
  "country": "JO",
  "createdAt": "2026-03-14T09:00:00Z",
  "updatedAt": "2026-10-02T13:25:10Z"
}

Retrieve your organisation

Returns the organisation the bearer token belongs to.

Requires org:read

Returns

200The organisation object.

Errors

  • 403PERMISSION_DENIEDYour role lacks the permission this call needs.
bash
curl -X GET "https://api.cx.na6iq.com/api/v1/org" \
  -H "Authorization: Bearer $NATIQ_TOKEN"
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/org', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
  },
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.get(
    "https://api.cx.na6iq.com/api/v1/org",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
)
res.raise_for_status()
data = res.json()
Response200
json
{
  "id": 12,
  "name": "Al-Noor Telecom",
  "status": "ACTIVE",
  "plan": null,
  "country": "JO",
  "createdAt": "2026-03-14T09:00:00Z",
  "updatedAt": "2026-10-02T13:25:10Z"
}

Update your organisation

Changes the organisation’s name or country. Send both fields; name is required, and omitting country clears it.

Requires org:write

Request body

  • namestringrequired
    New organisation name.
  • countrystringnullable
    New country. Written as sent, so null or omitting it clears it.

Returns

200The organisation object.

Errors

  • 400VALIDATION_FAILEDA field is malformed — see `error.details`.
  • 403PERMISSION_DENIEDYour role lacks the permission this call needs.
bash
curl -X PATCH "https://api.cx.na6iq.com/api/v1/org" \
  -H "Authorization: Bearer $NATIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Al-Noor Telecom Group",
  "country": "JO"
}'
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/org', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Al-Noor Telecom Group",
    "country": "JO"
  }),
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.patch(
    "https://api.cx.na6iq.com/api/v1/org",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
    json={
      "name": "Al-Noor Telecom Group",
      "country": "JO"
    },
)
res.raise_for_status()
data = res.json()
Response200
json
{
  "id": 12,
  "name": "Al-Noor Telecom Group",
  "status": "ACTIVE",
  "plan": null,
  "country": "JO",
  "createdAt": "2026-03-14T09:00:00Z",
  "updatedAt": "2026-10-02T13:25:10Z"
}

Retrieve the brand

Returns how the dashboard looks for your organisation. Any signed-in member can read it — an agent’s dashboard is branded too — so it needs no permission beyond a valid token. An organisation that never set a brand gets every field null, meaning the Natiq default.

Returns

200The organisation object.

bash
curl -X GET "https://api.cx.na6iq.com/api/v1/org/branding" \
  -H "Authorization: Bearer $NATIQ_TOKEN"
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/org/branding', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
  },
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.get(
    "https://api.cx.na6iq.com/api/v1/org/branding",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
)
res.raise_for_status()
data = res.json()
Response200
json
{
  "primaryColor": "#0b7285",
  "logoLightUrl": "https://assets.example.com/brand/12/logo-light.png",
  "logoDarkUrl": null,
  "markUrl": "https://assets.example.com/brand/12/mark.png",
  "faviconUrl": null,
  "productName": "Al-Noor Care",
  "tone": "NEUTRAL",
  "updatedAt": "2026-11-01T10:00:00Z"
}

Update the brand

Replaces the whole brand. Send every field, with null for “back to the default” — an omitted field is not kept. Each image URL must be exactly what Upload a brand image returned for that field’s kind; any other URL is refused.

Requires org:write

Request body

  • primaryColorstringnullable
    Brand colour as #rrggbb. The dashboard derives its whole palette from it. null is the Natiq default.
  • logoLightUrlstringnullable
    Full logo for light surfaces. Must be a URL returned by Upload a brand image for LOGO_LIGHT.
  • logoDarkUrlstringnullable
    Full logo for dark surfaces; falls back to the light one. Upload kind LOGO_DARK.
  • markUrlstringnullable
    Square mark for the 36px rail tile. Upload kind MARK.
  • faviconUrlstringnullable
    Browser tab icon. Upload kind FAVICON.
  • productNamestringnullable
    Replaces “Natiq Engagement” in the browser tab title.
  • tonestringnullable
    The greys: WARM (or null) is Natiq’s warm cream and ink; NEUTRAL is the same lightness with no hue.
    One of: WARMNEUTRAL

Returns

200The organisation object.

Errors

  • 400VALIDATION_FAILEDA colour is not `#rrggbb`, or an image URL was not issued for that field’s kind.
  • 403PERMISSION_DENIEDYour role lacks the permission this call needs.
bash
curl -X PUT "https://api.cx.na6iq.com/api/v1/org/branding" \
  -H "Authorization: Bearer $NATIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "primaryColor": "#0b7285",
  "logoLightUrl": "https://assets.example.com/brand/12/logo-light.png",
  "logoDarkUrl": null,
  "markUrl": "https://assets.example.com/brand/12/mark.png",
  "faviconUrl": null,
  "productName": "Al-Noor Care",
  "tone": "NEUTRAL"
}'
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/org/branding', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "primaryColor": "#0b7285",
    "logoLightUrl": "https://assets.example.com/brand/12/logo-light.png",
    "logoDarkUrl": null,
    "markUrl": "https://assets.example.com/brand/12/mark.png",
    "faviconUrl": null,
    "productName": "Al-Noor Care",
    "tone": "NEUTRAL"
  }),
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.put(
    "https://api.cx.na6iq.com/api/v1/org/branding",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
    json={
      "primaryColor": "#0b7285",
      "logoLightUrl": "https://assets.example.com/brand/12/logo-light.png",
      "logoDarkUrl": None,
      "markUrl": "https://assets.example.com/brand/12/mark.png",
      "faviconUrl": None,
      "productName": "Al-Noor Care",
      "tone": "NEUTRAL"
    },
)
res.raise_for_status()
data = res.json()
Response200
json
{
  "primaryColor": "#0b7285",
  "logoLightUrl": "https://assets.example.com/brand/12/logo-light.png",
  "logoDarkUrl": null,
  "markUrl": "https://assets.example.com/brand/12/mark.png",
  "faviconUrl": null,
  "productName": "Al-Noor Care",
  "tone": "NEUTRAL",
  "updatedAt": "2026-11-01T10:00:00Z"
}

Upload a brand image

Uploads a logo, mark or favicon and returns the public URL to save in the brand. The URL is public because favicons and logos load through plain <img> and <link> tags, which cannot send a bearer header. The body is multipart form data, not JSON:

sh
curl -X POST "https://api.cx.na6iq.com/api/v1/org/branding/assets" \
  -H "Authorization: Bearer $NATIQ_TOKEN" \
  -F "kind=LOGO_LIGHT" \
  -F "file=@logo.png"

kind is one of LOGO_LIGHT, LOGO_DARK, MARK or FAVICON. Saving the URL into the brand is a separate call.

Requires org:write

Returns

200The organisation object.

Errors

  • 400VALIDATION_FAILED`kind` is not one of the four, the file type is not supported, or the file is over 1 MB.
  • 502MEDIA_SCAN_UNAVAILABLEThe malware scan could not run, so the file was not accepted. Try again.
  • 403PERMISSION_DENIEDYour role lacks the permission this call needs.
bash
curl -X POST "https://api.cx.na6iq.com/api/v1/org/branding/assets" \
  -H "Authorization: Bearer $NATIQ_TOKEN"
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/org/branding/assets', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
  },
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.post(
    "https://api.cx.na6iq.com/api/v1/org/branding/assets",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
)
res.raise_for_status()
data = res.json()
Response200
json
{
  "url": "https://assets.example.com/brand/12/logo-light.png"
}

List users

Returns everyone in your organisation as a plain array, with the names of the roles each holds.

Requires admin:read

Returns

200The organisation object.

Errors

  • 403PERMISSION_DENIEDYour role lacks the permission this call needs.
bash
curl -X GET "https://api.cx.na6iq.com/api/v1/admin/users" \
  -H "Authorization: Bearer $NATIQ_TOKEN"
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/admin/users', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
  },
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.get(
    "https://api.cx.na6iq.com/api/v1/admin/users",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
)
res.raise_for_status()
data = res.json()
Response200
json
[
  {
    "id": 214,
    "orgId": 12,
    "username": "omar.khalil",
    "email": "omar@example.com",
    "status": "ACTIVE",
    "createdAt": "2026-03-14T09:05:00Z",
    "updatedAt": "2026-10-02T13:25:10Z",
    "roles": [
      "live_agent_agent"
    ]
  }
]

Invite a user

Emails an invitation. No password is involved: the account is created only when the invitee accepts the emailed link and chooses a password. Leave roleNames empty to give the baseline live_agent_agent role; unknown or non-assignable role names are rejected. Revoke a pending invitation with DELETE /admin/invitations/{invitationId} (answers 404 INVITATION_NOT_FOUND or 409 INVITATION_NOT_PENDING).

Requires admin:write

Request body

  • emailstringrequired
    The invitee’s email address.
  • roleNamesarray<string>nullable
    Roles to grant on acceptance. See List roles for the names.

Returns

201The organisation object.

Errors

  • 400VALIDATION_FAILEDThe email is blank or malformed.
  • 404ROLE_NOT_FOUNDA role name does not exist.
  • 403ROLE_NOT_ASSIGNABLEA role name cannot be granted by invitation, such as `platform_admin`.
  • 409INVITATION_PENDINGAn invitation to this address is already waiting to be accepted.
  • 409EMAIL_ALREADY_REGISTEREDThis address already has an account.
  • 403PERMISSION_DENIEDYour role lacks the permission this call needs.
bash
curl -X POST "https://api.cx.na6iq.com/api/v1/admin/users/invite" \
  -H "Authorization: Bearer $NATIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "rana@example.com",
  "roleNames": [
    "live_agent_agent"
  ]
}'
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/admin/users/invite', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "rana@example.com",
    "roleNames": [
      "live_agent_agent"
    ]
  }),
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.post(
    "https://api.cx.na6iq.com/api/v1/admin/users/invite",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
    json={
      "email": "rana@example.com",
      "roleNames": [
        "live_agent_agent"
      ]
    },
)
res.raise_for_status()
data = res.json()
Response201
json
{
  "id": 77,
  "email": "rana@example.com",
  "roleNames": [
    "live_agent_agent"
  ],
  "status": "PENDING",
  "expiresAt": "2026-11-14T08:00:00Z",
  "createdAt": "2026-11-07T08:00:00Z",
  "acceptedAt": null
}

List invitations

Returns the organisation’s invitations as a plain array. A PENDING invitation past expiresAt reads as EXPIRED.

Requires admin:read

Returns

200The organisation object.

Errors

  • 403PERMISSION_DENIEDYour role lacks the permission this call needs.
bash
curl -X GET "https://api.cx.na6iq.com/api/v1/admin/invitations" \
  -H "Authorization: Bearer $NATIQ_TOKEN"
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/admin/invitations', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
  },
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.get(
    "https://api.cx.na6iq.com/api/v1/admin/invitations",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
)
res.raise_for_status()
data = res.json()
Response200
json
[
  {
    "id": 77,
    "email": "rana@example.com",
    "roleNames": [
      "live_agent_agent"
    ],
    "status": "PENDING",
    "expiresAt": "2026-11-14T08:00:00Z",
    "createdAt": "2026-11-07T08:00:00Z",
    "acceptedAt": null
  }
]

List roles

Returns the roles you can grant. A role is a named bundle of permission keys. Roles with system: true are built in and read-only; the rest are yours. The system roles are org_admin, live_agent_admin, live_agent_agent, campaign_admin and builder_admin.

Requires admin:read

Returns

200The organisation object.

Errors

  • 403PERMISSION_DENIEDYour role lacks the permission this call needs.
bash
curl -X GET "https://api.cx.na6iq.com/api/v1/admin/roles" \
  -H "Authorization: Bearer $NATIQ_TOKEN"
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/admin/roles', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
  },
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.get(
    "https://api.cx.na6iq.com/api/v1/admin/roles",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
)
res.raise_for_status()
data = res.json()
Response200
json
[
  {
    "id": 3,
    "name": "live_agent_agent",
    "description": "Answers conversations in the Inbox.",
    "system": true,
    "permissions": [
      "liveagent.tickets:read",
      "liveagent.tickets:write",
      "liveagent.conversations:read",
      "liveagent.conversations:write"
    ]
  },
  {
    "id": 19,
    "name": "Billing team",
    "description": "Billing queue only.",
    "system": false,
    "permissions": [
      "liveagent.tickets:read",
      "liveagent.conversations:read"
    ]
  }
]