Get a merchant
Requires org:merchants:read or org:merchants:write. Scoped to the verified token organization; impersonated reads mask PII.
Authorization
oauth2 Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.
In: header
Path Parameters
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08"{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "date_of_birth": "2019-08-24", "gender": "string", "religion": "string", "id_number": "string", "personal_id_front": "string", "personal_id_back": "string", "business_name": "string", "business_type": "string", "store_type": "string", "merchant_category": "string", "address": "string", "is_business_registered": true, "business_age_months": 0, "phone_number": "string", "email": "string", "monthly_turnover": "string", "goods_turnover": { "duration": 1, "unit": "DAYS" }, "margin": "string", "risk_level": "string", "can_renew": true, "requested_amount": { "value": 0, "currency": "KES" }, "requested_tenure": { "duration": 1, "unit": "DAYS" }, "source": "string", "referred_by": "string", "branch": "string", "latitude": 0, "longitude": 0, "location_accuracy": 0, "next_of_kin_name": "string", "next_of_kin_relationship": "string", "next_of_kin_phone_number": "string", "transunion_screenshot": "string", "merchant_photo": "string", "business_registration_permit": "string", "proof_of_business": "string", "picture_of_store_front": "string", "picture_of_store_stocks": "string", "document_reviews": { "property1": null, "property2": null }, "approved_limit": { "value": 0, "currency": "KES" }, "status": "string", "local_id": "string", "external_id": "string", "organization_id": "string", "onboarding_status": "string", "migration_status": "NOT_MIGRATED", "user_id": "string", "account_id": "string", "migration_error": "string", "activated_at": "2019-08-24T14:15:22Z", "assigned_employee": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "email": "user@example.com", "phone_number": "string", "name": "string", "role": "string", "is_active": true }, "onboarded_by_employee": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "email": "user@example.com", "phone_number": "string", "name": "string", "role": "string", "is_active": true }, "statements": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "type": "PERSONAL", "document_key": "string", "created_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z"}{ "code": "INVALID_PARAMS", "description": "user_id must be a UUID", "identifier": "string", "invalid_params": [ { "path": "user_id", "reason": "must be a UUID", "sub_code": "string" } ]}{ "code": "INVALID_PARAMS", "description": "user_id must be a UUID", "identifier": "string", "invalid_params": [ { "path": "user_id", "reason": "must be a UUID", "sub_code": "string" } ]}{ "code": "INVALID_PARAMS", "description": "user_id must be a UUID", "identifier": "string", "invalid_params": [ { "path": "user_id", "reason": "must be a UUID", "sub_code": "string" } ]}{ "code": "INVALID_PARAMS", "description": "user_id must be a UUID", "identifier": "string", "invalid_params": [ { "path": "user_id", "reason": "must be a UUID", "sub_code": "string" } ]}{ "code": "INVALID_PARAMS", "description": "user_id must be a UUID", "identifier": "string", "invalid_params": [ { "path": "user_id", "reason": "must be a UUID", "sub_code": "string" } ]}{ "code": "INVALID_PARAMS", "description": "user_id must be a UUID", "identifier": "string", "invalid_params": [ { "path": "user_id", "reason": "must be a UUID", "sub_code": "string" } ]}{ "code": "INVALID_PARAMS", "description": "user_id must be a UUID", "identifier": "string", "invalid_params": [ { "path": "user_id", "reason": "must be a UUID", "sub_code": "string" } ]}Create a merchant POST
The canonical merchant-creation API for all products. Requires org:merchants:write. Sales App generates the id; clients cannot supply an id or organization. The verified token selects the tenant (Cowdi uses the organic book). Creates an opportunity with its initial activity and optional employee assignment in one transaction. Reuse idempotency_key with identical details to recover the same id after a timeout. A changed request or a phone/ID owned by another merchant returns 409. user_id links the merchant to an existing Cowdi user (a service onboarding one of its users); one merchant per user per organization, so naming a user already linked there returns that merchant with 200 instead of creating another. Core registration must use the returned id; it does not generate another identity. Product setup, invitations and activation remain separate lifecycle operations.
List merchants GET
List every merchant under the organization. Requires the caller's `org:merchants:read` permission on the organization. Returns every match; the response is not paginated.