Create a client

POST/clientsCreate a client

Creates a new client in the authenticated organization. The server auto-wires any matching integration assignment rules based on the supplied domain (same behaviour as the dashboard create flow).

organizationId must not be included in the body. The organization is resolved from the bearer token; a body-borne organizationId is rejected with 400 invalid_argument rather than silently overridden.

Request body

required

application/json

objectCreateClientRequest

accountManagerIdsarray of string · uuid

Optional initial set of account-manager user IDs. Each ID must reference a user in the caller's organization; cross-tenant assignment returns `400 invalid_argument` naming the offending ID.

Show child attributes

clientTypestring

Optional lifecycle stage at create-time. Omitted → defaults to `active`. Invalid values return `400 invalid_argument` naming the offending value.

one of "prospect", "active", "churned"

domainstring

Primary email domain — used by the integration assignment-rule engine to auto-attach inbound communications to this client. When omitted, the rule engine does not auto-assign based on domain.

namestringrequired

Display name of the new client.

Example request

{
  "accountManagerIds": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "clientType": "prospect",
  "domain": "globex.com",
  "name": "Globex"
}

Responses

Headers

X-RateLimit-Limit

The request cap for the tighter of the per-organization / per-endpoint windows that applied to this request.

X-RateLimit-Remaining

Requests remaining in the current window.

X-RateLimit-Reset

Unix timestamp (seconds) when the current window resets.

value

allOf · 2 options

Option 1objectEnvelope

datavaluerequired

The response payload — shape depends on the endpoint.

metaobjectrequired

Pagination metadata — populated on list endpoints, empty on single-resource endpoints.

Show child attributes

cursornull | string

Opaque cursor to pass to the next request.

hasMoreboolean | null

True when further pages of results are available.

Option 2object

dataobject

A client record (partner's CRM account / customer). The fields `email`, `phone`, `company`, and `notes` from the v1.0 spec document are not yet populated — tracked as a follow-up.

Show child attributes

accountManagersarray of objectrequired

Users assigned as account managers for this client. Peers — no primary/secondary distinction. Always present; an empty array signals no managers are assigned.

Show child attributes

Show array items

Minimal user identity surfaced on client records.

emailstring · emailrequired

firstNamestringrequired

lastNamestringrequired

userIdstring · uuidrequired

Stable UUID for this user.

clientTypestringrequired

Lifecycle stage of the client (status, not legal entity type). `prospect` → `active` → `churned` is the canonical progression. Use this to answer pipeline/status questions ("who are my prospects?", "who has churned?"). Defaults to `active` on creation when the caller omits the field.

one of "prospect", "active", "churned"

createdAtstring · date-timerequired

UTC timestamp when the client was created.

domainnull | string

Primary email domain used to auto-assign communications (e.g. `acme.com`).

idstring · uuidrequired

Stable UUID for this client.

namestringrequired

Display name of the client.

updatedAtstring · date-timerequired

UTC timestamp of the most recent update.

Example response

{
  "data": {
    "accountManagers": [
      {
        "email": "user@example.com",
        "firstName": "string",
        "lastName": "string",
        "userId": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "clientType": "active",
    "createdAt": "2026-06-09T00:00:00Z",
    "domain": "acme.com",
    "id": "8b2d1c4e-3f5a-4e2b-9c8f-1e2d3c4b5a6f",
    "name": "Acme Corp",
    "updatedAt": "2026-06-09T00:00:00Z"
  },
  "meta": {
    "cursor": "string",
    "hasMore": true
  }
}

objectErrorEnvelope

errorobjectrequired

Show child attributes

codestringrequired

Machine-readable error category.

one of "unauthorized", "forbidden", "not_found", "invalid_argument", "conflict", "rate_limited", "internal_error", "not_implemented"

detailsobject

Optional per-code context (field names, retry windows, …).

messagestringrequired

Human-readable description — intended for operator logs, not end-user display.

Example response

{
  "error": {
    "code": "invalid_argument",
    "message": "limit must be an integer between 1 and 100"
  }
}

objectErrorEnvelope

errorobjectrequired

Show child attributes

codestringrequired

Machine-readable error category.

one of "unauthorized", "forbidden", "not_found", "invalid_argument", "conflict", "rate_limited", "internal_error", "not_implemented"

detailsobject

Optional per-code context (field names, retry windows, …).

messagestringrequired

Human-readable description — intended for operator logs, not end-user display.

Example response

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication required"
  }
}

Headers

Retry-After

Seconds the client should wait before retrying.

objectErrorEnvelope

errorobjectrequired

Show child attributes

codestringrequired

Machine-readable error category.

one of "unauthorized", "forbidden", "not_found", "invalid_argument", "conflict", "rate_limited", "internal_error", "not_implemented"

detailsobject

Optional per-code context (field names, retry windows, …).

messagestringrequired

Human-readable description — intended for operator logs, not end-user display.

Example response

{
  "error": {
    "code": "rate_limited",
    "details": {
      "retry_after_seconds": 30
    },
    "message": "Rate limit exceeded"
  }
}

Examples

curl -X POST 'https://api.salfio.com/v1/clients' \
  -H 'Content-Type: application/json' \
  -d '{"accountManagerIds":["00000000-0000-0000-0000-000000000000"],"clientType":"prospect","domain":"globex.com","name":"Globex"}'

const response = await fetch('https://api.salfio.com/v1/clients', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"accountManagerIds":["00000000-0000-0000-0000-000000000000"],"clientType":"prospect","domain":"globex.com","name":"Globex"}),
});
const data = await response.json();

const response = await fetch('https://api.salfio.com/v1/clients', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: "{\"accountManagerIds\":[\"00000000-0000-0000-0000-000000000000\"],\"clientType\":\"prospect\",\"domain\":\"globex.com\",\"name\":\"Globex\"}" });
console.log(await response.json());

import requests

response = requests.request(
    "POST",
    "https://api.salfio.com/v1/clients",
    headers={"Content-Type": "application/json"},
    data='{"accountManagerIds":["00000000-0000-0000-0000-000000000000"],"clientType":"prospect","domain":"globex.com","name":"Globex"}',
)
print(response.json())

package main

import (
	"context"
	"net/http"
	"strings"
)

func main() {
	ctx := context.Background()
	body := strings.NewReader(`{"accountManagerIds":["00000000-0000-0000-0000-000000000000"],"clientType":"prospect","domain":"globex.com","name":"Globex"}`)
	req, err := http.NewRequestWithContext(ctx, "POST", "https://api.salfio.com/v1/clients", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}

<?php
$request = curl_init("https://api.salfio.com/v1/clients");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($request, CURLOPT_POSTFIELDS, "{\"accountManagerIds\":[\"00000000-0000-0000-0000-000000000000\"],\"clientType\":\"prospect\",\"domain\":\"globex.com\",\"name\":\"Globex\"}");
curl_setopt($request, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($request);
curl_close($request);

var request = HttpRequest.newBuilder(URI.create("https://api.salfio.com/v1/clients"))
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"accountManagerIds\":[\"00000000-0000-0000-0000-000000000000\"],\"clientType\":\"prospect\",\"domain\":\"globex.com\",\"name\":\"Globex\"}"))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("https://api.salfio.com/v1/clients")
request = Net::HTTPGenericRequest.new("POST", true, true, uri)
request['Content-Type'] = 'application/json'
request.body = "{\"accountManagerIds\":[\"00000000-0000-0000-0000-000000000000\"],\"clientType\":\"prospect\",\"domain\":\"globex.com\",\"name\":\"Globex\"}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.salfio.com/v1/clients");
request.Content = new StringContent("{\"accountManagerIds\":[\"00000000-0000-0000-0000-000000000000\"],\"clientType\":\"prospect\",\"domain\":\"globex.com\",\"name\":\"Globex\"}", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);

{
  "data": {
    "accountManagers": [
      {
        "email": "user@example.com",
        "firstName": "string",
        "lastName": "string",
        "userId": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "clientType": "active",
    "createdAt": "2026-06-09T00:00:00Z",
    "domain": "acme.com",
    "id": "8b2d1c4e-3f5a-4e2b-9c8f-1e2d3c4b5a6f",
    "name": "Acme Corp",
    "updatedAt": "2026-06-09T00:00:00Z"
  },
  "meta": {
    "cursor": "string",
    "hasMore": true
  }
}

{
  "error": {
    "code": "invalid_argument",
    "message": "limit must be an integer between 1 and 100"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication required"
  }
}

{
  "error": {
    "code": "rate_limited",
    "details": {
      "retry_after_seconds": 30
    },
    "message": "Rate limit exceeded"
  }
}

Search documentation

Request body

Responses

Headers

Headers

Documentation menu