Groups

Create group destination

Registers a group already authorized by the account connector.

POST/groupsgroups:write

BEHAVIOR

The change is validated and persisted in the key account before responding. Query the returned resource as the source of truth.

EFFECT

It can change the resource and emit the corresponding domain event.

REPETITION

On network failure, confirm the resource status before retrying. Automatically redo only 429 and 5xx with backoff and jitter.

Request

namestring · bodyGroup name.minLength 2 · maxLength 160mandatory

external_idstring · bodyIdentifier returned by the connector; never comes back in response.minLength 2 · maxLength 240mandatory

connection_idstring · bodyConnection that manages the group.optional

segment_idstring · bodyInitial segment.optional

rolestring · bodyRole: shipping, monitor, or both.optional

capacityinteger · bodyOperational capacity.min 1 · max 1000000optional

automationboolean · bodyActivates automation.optional

AuthorizationBearer ach_live_...

Acceptapplication/json

Scopegroups:write

Executable example

curl

curl -X POST 'https://achadu.com/api/v1/groups' \
  -H 'Authorization: Bearer ach_live_...' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{
  "name": "My integration",
  "external_id": "string",
  "connection_id": "string",
  "segment_id": "string",
  "role": "string"
}'

Response and errors

Every response includes request_id. Lists add pagination; mutable resources return the persisted state after the operation.

201 application/json

{
  "data": {
    "id": "grp_01J...",
    "name": "Home deals",
    "members": 842,
    "active": 1,
    "capacity": 1024,
    "segment_id": "seg_01J..."
  },
  "created": true,
  "request_id": "req_01J..."
}

201Resource created and persisted.

400Invalid parameter, body or transition.

401Missing, invalid, expired or revoked key.

402The account plan does not release this interface.

403A chave precisa do escopo groups:write.

404Feature does not exist in this account.

409The current state prevents this operation.

413The JSON body exceeds 128 KB.

429The 120 requests per minute window has been exceeded.

Create group destination

Request

Executable example

Response and errors

Related operations