openapi: 3.2.0 info: title: DataCandy Client Management API description: 'REST API for the DataCandy platform. Provides endpoints for managing merchants, clients, contacts, account types, transactions, webhooks, and portal configuration. All endpoints require a JWT bearer token unless stated otherwise.' version: 26.7.1.0-d9107e6 servers: - url: / description: '' security: - JWT: {} tags: - name: Client Management paths: /v1/clients: get: operationId: api_v1clients_get_collection tags: - Client Management responses: 200: description: List of clients. content: application/ld+json: schema: type: object description: Client.jsonld-client.read collection. allOf: - $ref: '#/components/schemas/HydraCollectionBaseSchema' - type: object required: - hydra:member properties: hydra:member: type: array items: $ref: '#/components/schemas/Client.jsonld-client.read' 403: description: Forbidden — token does not have the required role. content: application/json: schema: type: object properties: code: type: integer example: 403 message: type: string example: Access Denied. 401: description: Unauthorized — missing or invalid JWT token. content: application/json: schema: type: object properties: code: type: integer example: 401 message: type: string example: JWT Token not found summary: Retrieve all clients in the portfolio. description: Retrieves the collection of Client resources. parameters: - name: page in: query description: The collection page number required: false deprecated: false schema: type: integer default: 1 style: form explode: false - name: itemsPerPage in: query description: The number of items per page required: false deprecated: false schema: type: integer default: 30 minimum: 0 maximum: 30 style: form explode: false security: - JWT: {} post: operationId: api_v1clients_post tags: - Client Management responses: 201: description: Client created successfully. content: application/ld+json: schema: $ref: '#/components/schemas/Client.jsonld-client.read' 400: description: Invalid input content: application/ld+json: schema: $ref: '#/components/schemas/Error.jsonld' application/problem+json: schema: $ref: '#/components/schemas/Error' application/json: schema: $ref: '#/components/schemas/Error' links: null 422: description: Validation error — see violations array for field-level details. content: application/ld+json: schema: $ref: '#/components/schemas/ConstraintViolation.jsonld' application/problem+json: schema: $ref: '#/components/schemas/ConstraintViolation' application/json: schema: $ref: '#/components/schemas/ConstraintViolation' 403: description: Forbidden — token does not have the required role. content: application/json: schema: type: object properties: code: type: integer example: 403 message: type: string example: Access Denied. 401: description: Unauthorized — missing or invalid JWT token. content: application/json: schema: type: object properties: code: type: integer example: 401 message: type: string example: JWT Token not found summary: Create a new client. description: "Creates a new client and provisions its database, account types, and product packages. \n**Required fields:** `name`, `hostname`, `country`, `timeZone`, `currency`, `languages`, `programs`, `companyInfo` \n**For loyalty clients:** also requires `accumulationRatioNumerator`, `accumulationRatioDenominator`, `debitRatioNumerator`, `debitRatioDenominator` \n**For Moneris portfolios:** also requires `configureEgift`, `configureEloyalty`, `configureMemberPortal`, `giftCardsRestrictedWhereActivated`, `enableSboEmailAndSms`" parameters: {} requestBody: description: The new Client resource content: application/ld+json: schema: $ref: '#/components/schemas/Client-client.write' required: true security: - JWT: {} /v1/clients/{id}: get: operationId: api_v1clients_id_get tags: - Client Management responses: 200: description: Client retrieved successfully. content: application/ld+json: schema: $ref: '#/components/schemas/Client.jsonld-client.read' 403: description: Forbidden — token does not have the required role. content: application/json: schema: type: object properties: code: type: integer example: 403 message: type: string example: Access Denied. 404: description: Not found — the requested resource does not exist. content: application/ld+json: schema: $ref: '#/components/schemas/Error.jsonld' application/problem+json: schema: $ref: '#/components/schemas/Error' application/json: schema: $ref: '#/components/schemas/Error' 401: description: Unauthorized — missing or invalid JWT token. content: application/json: schema: type: object properties: code: type: integer example: 401 message: type: string example: JWT Token not found summary: Retrieve a client by ID. description: Retrieves a Client resource. parameters: - name: id in: path description: Numeric client ID. required: true deprecated: false schema: type: integer style: simple explode: false example: 42 security: - JWT: {} patch: operationId: api_v1clients_id_patch tags: - Client Management responses: 200: description: Client updated successfully. content: application/ld+json: schema: $ref: '#/components/schemas/Client.jsonld-client.read' 400: description: Invalid input content: application/ld+json: schema: $ref: '#/components/schemas/Error.jsonld' application/problem+json: schema: $ref: '#/components/schemas/Error' application/json: schema: $ref: '#/components/schemas/Error' links: null 422: description: Validation error — see violations array for field-level details. content: application/ld+json: schema: $ref: '#/components/schemas/ConstraintViolation.jsonld' application/problem+json: schema: $ref: '#/components/schemas/ConstraintViolation' application/json: schema: $ref: '#/components/schemas/ConstraintViolation' 403: description: Forbidden — token does not have the required role. content: application/json: schema: type: object properties: code: type: integer example: 403 message: type: string example: Access Denied. 404: description: Not found — the requested resource does not exist. content: application/ld+json: schema: $ref: '#/components/schemas/Error.jsonld' application/problem+json: schema: $ref: '#/components/schemas/Error' application/json: schema: $ref: '#/components/schemas/Error' 401: description: Unauthorized — missing or invalid JWT token. content: application/json: schema: type: object properties: code: type: integer example: 401 message: type: string example: JWT Token not found summary: Update an existing client. description: Updates the Client resource. parameters: - name: id in: path description: Numeric client ID. required: true deprecated: false schema: type: integer style: simple explode: false example: 42 requestBody: description: The updated Client resource content: application/merge-patch+json: schema: $ref: '#/components/schemas/Client-client.patch.jsonMergePatch' required: true security: - JWT: {} /v1/clients/{id}/complete: post: operationId: api_v1clients_idcomplete_post tags: - Client Management responses: 201: description: Client resource created content: application/ld+json: schema: $ref: '#/components/schemas/Client.jsonld-client.complete.read' links: null 400: description: Invalid input content: application/ld+json: schema: $ref: '#/components/schemas/Error.jsonld' application/problem+json: schema: $ref: '#/components/schemas/Error' application/json: schema: $ref: '#/components/schemas/Error' links: null 422: description: Validation error — see violations array for field-level details. content: application/ld+json: schema: $ref: '#/components/schemas/ConstraintViolation.jsonld' application/problem+json: schema: $ref: '#/components/schemas/ConstraintViolation' application/json: schema: $ref: '#/components/schemas/ConstraintViolation' 403: description: Forbidden — token does not have the required role. content: application/json: schema: type: object properties: code: type: integer example: 403 message: type: string example: Access Denied. 200: description: Client onboarding completed. 401: description: Unauthorized — missing or invalid JWT token. content: application/json: schema: type: object properties: code: type: integer example: 401 message: type: string example: JWT Token not found 404: description: Not found — the requested resource does not exist. summary: Complete client onboarding. description: 'Marks onboarding as complete and records the `completedOn` timestamp. After this call the client is active and ready to process transactions.' parameters: - name: id in: path description: Numeric client ID. required: true deprecated: false schema: type: integer style: simple explode: false example: 42 requestBody: description: The new Client resource content: application/ld+json: schema: $ref: '#/components/schemas/Client-client.complete' required: true security: - JWT: {} components: schemas: Error: type: object description: A representation of common errors. properties: title: readOnly: true description: A short, human-readable summary of the problem. type: - string - 'null' detail: readOnly: true description: A human-readable explanation specific to this occurrence of the problem. type: - string - 'null' status: type: - number - 'null' examples: - 404 default: 400 instance: readOnly: true description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. type: - string - 'null' type: readOnly: true description: A URI reference that identifies the problem type type: string ConstraintViolation.jsonld: allOf: - $ref: '#/components/schemas/HydraItemBaseSchema' - type: object properties: status: default: 422 type: integer violations: type: array items: type: object properties: propertyPath: type: string description: The property path of the violation message: type: string description: The message associated with the violation code: type: string description: The code of the violation hint: type: string description: An extra hint to understand the violation payload: type: object additionalProperties: true description: The serialized payload of the violation required: - propertyPath - message detail: readOnly: true type: string description: readOnly: true type: string type: readOnly: true type: string title: readOnly: true type: - string - 'null' instance: readOnly: true type: - string - 'null' description: Unprocessable entity Client-client.write: type: object required: - name - hostname - country - timeZone - currency - companyInfo properties: name: minLength: 2 maxLength: 128 description: Name representing the client type: - string - 'null' hostname: minLength: 1 maxLength: 60 pattern: ^((?!\-)[a-z0-9\-]*(?