Partner API API

Generated from api/openapi.public.yaml, the same spec the API serves. Try these operations in the API console; errors are Problem Details.

Get the partner of the key

GET /api/v1/partner

Operation id	getPartnerProfile
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.account:view
Plan feature	workspace.core

Responses

Status	Description	Body
200	OK	application/json: PartnerProfileBody
default	Error	application/problem+json: Problem

Example

curl -X GET "https://api.nexafone.so/api/v1/partner" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY"

List the partner’s stores

GET /api/v1/partner/stores

Operation id	listPartnerApiStores
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.stores:view
Plan feature	workspace.core

Parameters

Name	In	Type	Required	Description
cursor	query	string		The next value of the previous page
limit	query	integer (int64)

Responses

Status	Description	Body
200	OK	application/json: StoresBody
default	Error	application/problem+json: Problem

Example

curl -X GET "https://api.nexafone.so/api/v1/partner/stores" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY"

Create a store, or return the one with this externalRef

POST /api/v1/partner/stores

Creates a workspace for the store on the partner’s default plan and answers 201; when the partner already has a store with this externalRef it answers 200 with that store and changes nothing.

Operation id	createPartnerStore
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.stores:manage
Plan feature	workspace.core

Request body

application/json: NewStoreBody

Field	Type	Required	Description
country	string	yes	ISO 3166-1 alpha-2, such as SO (pattern ^[A-Za-z]{2}$)
externalRef	string	yes	The partner’s own id for the store; creating again with the same value returns the same store (min length 1, max length 255, pattern ^[A-Za-z0-9._:-]+$)
locale	"en" | "so" | "ar"	yes
name	string	yes	(min length 1, max length 120)
owner	StoreOwnerBody	yes
timezone	string	yes	IANA time zone, such as Africa/Mogadishu (min length 1, max length 64)

Responses

Status	Description	Body
201	Created	application/json: StoreBody
409	Conflict	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X POST "https://api.nexafone.so/api/v1/partner/stores" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"string","externalRef":"string","locale":"en","name":"string","owner":{"email":"[email protected]","name":"string"},"timezone":"string"}'

Get a store by its externalRef

GET /api/v1/partner/stores/{externalRef}

Operation id	getPartnerStore
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.stores:view
Plan feature	workspace.core

Parameters

Name	In	Type	Required	Description
externalRef	path	string	yes	The partner’s own id for the store

Responses

Status	Description	Body
200	OK	application/json: StoreBody
404	Not Found	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X GET "https://api.nexafone.so/api/v1/partner/stores/{externalRef}" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY"

Rename, close or reopen a store

PATCH /api/v1/partner/stores/{externalRef}

Operation id	updatePartnerStore
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.stores:manage
Plan feature	workspace.core

Parameters

Name	In	Type	Required	Description
externalRef	path	string	yes	The partner’s own id for the store

Request body

application/json: StoreChangeBody

Field	Type	Required	Description
name	string		(min length 1, max length 120)
status	"active" | "suspended"		suspended closes the store and keeps its data; active reopens a store the partner closed

Responses

Status	Description	Body
200	OK	application/json: StoreBody
404	Not Found	application/problem+json: Problem
409	Conflict	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X PATCH "https://api.nexafone.so/api/v1/partner/stores/{externalRef}" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Close a store

POST /api/v1/partner/stores/{externalRef}/close

Suspends the store: it becomes read-only and keeps its data. PATCH status active reopens it.

Operation id	closePartnerStore
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.stores:manage
Plan feature	workspace.core

Parameters

Name	In	Type	Required	Description
externalRef	path	string	yes	The partner’s own id for the store

Responses

Status	Description	Body
200	OK	application/json: StoreBody
404	Not Found	application/problem+json: Problem
409	Conflict	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X POST "https://api.nexafone.so/api/v1/partner/stores/{externalRef}/close" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY"

Change a user’s role and teams in a store

PUT /api/v1/partner/stores/{externalRef}/members/{partnerUserId}

The user must have signed in to the store through a partner session. Their open screens fetch their access again at once. A store keeps at least one owner, and a role that needs a seat takes one (no_free_seat when the store has none).

Operation id	updatePartnerStoreMember
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.stores:manage
Plan feature	workspace.core

Parameters

Name	In	Type	Required	Description
externalRef	path	string	yes	The partner’s own id for the store
partnerUserId	path	string	yes	The partner’s id for the user: the sub of its user tokens

Request body

application/json: UpdatePartnerMemberInputBody

Field	Type	Required	Description
role	string	yes	owner, admin, supervisor, agent or viewer (min length 1, max length 64)
teams	array of string		The store’s team ids the user is in; absent leaves the teams as they are (max 50 items)

Responses

Status	Description	Body
200	OK	application/json: PartnerMemberBody
403	Forbidden	application/problem+json: Problem
404	Not Found	application/problem+json: Problem
409	Conflict	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X PUT "https://api.nexafone.so/api/v1/partner/stores/{externalRef}/members/{partnerUserId}" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"string"}'

Disable a user’s membership of a store

DELETE /api/v1/partner/stores/{externalRef}/members/{partnerUserId}

The user can no longer open the store: requests to it are refused at once and its live updates stop within seconds; a session left with no store it can open ends. Leaving a store out of the user tokens does not do this, and a later user token that lists the store enables the membership again.

Operation id	disablePartnerStoreMember
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.stores:manage
Plan feature	workspace.core

Parameters

Name	In	Type	Required	Description
externalRef	path	string	yes	The partner’s own id for the store
partnerUserId	path	string	yes	The partner’s id for the user: the sub of its user tokens

Responses

Status	Description	Body
204	No Content
404	Not Found	application/problem+json: Problem
409	Conflict	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X DELETE "https://api.nexafone.so/api/v1/partner/stores/{externalRef}/members/{partnerUserId}" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY"

List the partner’s webhook endpoints

GET /api/v1/partner/webhook-endpoints

Operation id	listPartnerWebhookEndpoints
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.webhooks:manage
Plan feature	workspace.core

Responses

Status	Description	Body
200	OK	application/json: WebhookEndpointsOutputBody
default	Error	application/problem+json: Problem

Example

curl -X GET "https://api.nexafone.so/api/v1/partner/webhook-endpoints" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY"

Register a partner-wide webhook endpoint

POST /api/v1/partner/webhook-endpoints

It receives the subscribed events of every store of the partner; the envelope’s partner.storeExternalRef names the store. Every delivery is signed like a store’s own: Nexafon-Signature: t=,v1=<hex HMAC-SHA256 of “.” keyed with the secret>. The secret is in this response only.

Operation id	createPartnerWebhookEndpoint
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.webhooks:manage
Plan feature	workspace.core

Request body

application/json: CreatePartnerEndpointInputBody

Field	Type	Required	Description
description	string		(max length 200)
events	array of string	yes	Event types from GET /partner/webhook-event-types (min 1 items, max 64 items)
url	string	yes	An https URL on the public internet (min length 8, max length 2048)

Responses

Status	Description	Body
201	Created	application/json: WebhookSecretOutputBody
409	Conflict	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X POST "https://api.nexafone.so/api/v1/partner/webhook-endpoints" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":["string"],"url":"string"}'

Get a partner webhook endpoint

GET /api/v1/partner/webhook-endpoints/{endpointId}

Operation id	getPartnerWebhookEndpoint
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.webhooks:manage
Plan feature	workspace.core

Parameters

Name	In	Type	Required	Description
endpointId	path	string	yes	Webhook endpoint id (UUID)

Responses

Status	Description	Body
200	OK	application/json: WebhookEndpointBody
404	Not Found	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X GET "https://api.nexafone.so/api/v1/partner/webhook-endpoints/{endpointId}" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY"

Change a partner webhook endpoint, or turn it off or back on

PATCH /api/v1/partner/webhook-endpoints/{endpointId}

Operation id	updatePartnerWebhookEndpoint
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.webhooks:manage
Plan feature	workspace.core

Parameters

Name	In	Type	Required	Description
endpointId	path	string	yes	Webhook endpoint id (UUID)

Request body

application/json: UpdatePartnerEndpointInputBody

Field	Type	Required	Description
description	string		(max length 200)
events	array of string or null		(min 1 items, max 64 items)
status	"active" | "disabled"		active turns a disabled endpoint back on
url	string		(min length 8, max length 2048)

Responses

Status	Description	Body
200	OK	application/json: WebhookEndpointBody
404	Not Found	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X PATCH "https://api.nexafone.so/api/v1/partner/webhook-endpoints/{endpointId}" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Delete a partner webhook endpoint and its delivery log

DELETE /api/v1/partner/webhook-endpoints/{endpointId}

Operation id	deletePartnerWebhookEndpoint
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.webhooks:manage
Plan feature	workspace.core

Parameters

Name	In	Type	Required	Description
endpointId	path	string	yes	Webhook endpoint id (UUID)

Responses

Status	Description	Body
204	No Content
404	Not Found	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X DELETE "https://api.nexafone.so/api/v1/partner/webhook-endpoints/{endpointId}" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY"

List every delivery attempt to a partner endpoint

GET /api/v1/partner/webhook-endpoints/{endpointId}/deliveries

Operation id	listPartnerWebhookDeliveries
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.webhooks:manage
Plan feature	workspace.core

Parameters

Name	In	Type	Required	Description
endpointId	path	string	yes	Webhook endpoint id (UUID)
eventId	query	string (uuid)		Only this event’s attempts
status	query	"succeeded" | "failed"
cursor	query	string		The next value of the previous page
limit	query	integer (int64)

Responses

Status	Description	Body
200	OK	application/json: WebhookDeliveriesOutputBody
404	Not Found	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X GET "https://api.nexafone.so/api/v1/partner/webhook-endpoints/{endpointId}/deliveries" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY"

Send an event to a partner endpoint again

POST /api/v1/partner/webhook-endpoints/{endpointId}/events/{eventId}/replay

The event keeps its id. It is retried on the usual schedule; the delivery log shows every attempt.

Operation id	replayPartnerWebhookEndpointEvent
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.webhooks:manage
Plan feature	workspace.core

Parameters

Name	In	Type	Required	Description
endpointId	path	string	yes	Webhook endpoint id (UUID)
eventId	path	string	yes	Event id (UUID) from the delivery log

Responses

Status	Description	Body
202	Accepted
404	Not Found	application/problem+json: Problem
409	Conflict	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X POST "https://api.nexafone.so/api/v1/partner/webhook-endpoints/{endpointId}/events/{eventId}/replay" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY"

Replace a partner webhook endpoint’s signing secret

POST /api/v1/partner/webhook-endpoints/{endpointId}/rotate-secret

Until previousSecretExpiresAt deliveries carry a v1 signature for each secret. The new secret is in this response only.

Operation id	rotatePartnerWebhookEndpointSecret
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.webhooks:manage
Plan feature	workspace.core

Parameters

Name	In	Type	Required	Description
endpointId	path	string	yes	Webhook endpoint id (UUID)
keepPreviousHours	query	integer (int64)		How long deliveries are also signed with the replaced secret

Responses

Status	Description	Body
200	OK	application/json: WebhookSecretOutputBody
404	Not Found	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X POST "https://api.nexafone.so/api/v1/partner/webhook-endpoints/{endpointId}/rotate-secret" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY"

Send a webhook.test event to a partner endpoint

POST /api/v1/partner/webhook-endpoints/{endpointId}/test

Works on a disabled endpoint too. It is tried once; the delivery log shows the result.

Operation id	sendPartnerWebhookTest
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.webhooks:manage
Plan feature	workspace.core

Parameters

Name	In	Type	Required	Description
endpointId	path	string	yes	Webhook endpoint id (UUID)

Responses

Status	Description	Body
202	Accepted	application/json: WebhookTestOutputBody
404	Not Found	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X POST "https://api.nexafone.so/api/v1/partner/webhook-endpoints/{endpointId}/test" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY"

List the events a partner endpoint can subscribe to

GET /api/v1/partner/webhook-event-types

Operation id	listPartnerWebhookEventTypes
Authentication	A secret partner key (psk_live_… or psk_test_…), from a server only.
Permission (key scope)	partner.webhooks:manage
Plan feature	workspace.core

Responses

Status	Description	Body
200	OK	application/json: WebhookEventTypesOutputBody
default	Error	application/problem+json: Problem

Example

curl -X GET "https://api.nexafone.so/api/v1/partner/webhook-event-types" \
  -H "Authorization: Bearer $NEXAFON_PARTNER_SECRET_KEY"