Customers API

Buscá clientes, creá una identidad cuando no exista y consultá su estado de loyalty.

Operaciones

GET/api/customers/{id}/stateGET/api/customers/searchPOST/api/customers

GET/api/customers/{id}/state

Read sanitized customer loyalty state

Returns points, current tier and the most recent operation without profile PII.

Scopes requeridos

customers.read

Parámetros y headers

idpathrequerido

{
  "maximum": 9007199254740991,
  "minimum": 1,
  "type": "integer"
}

x-request-idheaderopcional

Optional caller correlation identifier.

{
  "type": "string"
}

X-Tenant-IDheaderopcional

Optional consistency hint; it never replaces the credential tenant.

{
  "maximum": 9007199254740991,
  "minimum": 1,
  "type": "integer"
}

X-Tenant-Subdomainheaderopcional

Optional consistency hint; it must resolve to the credential tenant.

{
  "type": "string"
}

Request body

No aplica

Respuestas

HTTP 200 — Sanitized customer loyalty state.

{
  "additionalProperties": false,
  "properties": {
    "data": {
      "additionalProperties": false,
      "properties": {
        "customer": {
          "additionalProperties": false,
          "properties": {
            "active": {
              "type": "boolean"
            },
            "currentTier": {
              "oneOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "minimum": 1,
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "name"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "id": {
              "minimum": 1,
              "type": "integer"
            },
            "points": {
              "type": "number"
            },
            "programId": {
              "minimum": 1,
              "type": "integer"
            }
          },
          "required": [
            "id",
            "programId",
            "points",
            "currentTier",
            "active"
          ],
          "type": "object"
        },
        "recentOperation": {
          "oneOf": [
            {
              "additionalProperties": false,
              "properties": {
                "amount": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "externalReference": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "occurredAt": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "points": {
                  "type": "number"
                },
                "transactionId": {
                  "minimum": 1,
                  "type": "integer"
                },
                "type": {
                  "type": "string"
                }
              },
              "required": [
                "transactionId",
                "type",
                "points",
                "amount",
                "occurredAt",
                "externalReference"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "customer",
        "recentOperation"
      ],
      "type": "object"
    },
    "ok": {
      "const": true
    }
  },
  "required": [
    "ok",
    "data"
  ],
  "type": "object"
}

HTTP 400 — Invalid customer identifier or tenant hint.

Códigos de error

ambiguous_tenant_hintinvalid_customer_idinvalid_tenant_hint

{
  "additionalProperties": false,
  "properties": {
    "error": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "enum": [
            "invalid_customer_id",
            "invalid_tenant_hint",
            "ambiguous_tenant_hint"
          ],
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "ok": {
      "const": false
    }
  },
  "required": [
    "ok",
    "error"
  ],
  "type": "object"
}

HTTP 401 — Missing or invalid API key.

Códigos de error

invalid_api_keymissing_api_key

{
  "additionalProperties": false,
  "properties": {
    "error": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "enum": [
            "missing_api_key",
            "invalid_api_key"
          ],
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "ok": {
      "const": false
    }
  },
  "required": [
    "ok",
    "error"
  ],
  "type": "object"
}

HTTP 403 — Scope or tenant boundary denial.

Códigos de error

insufficient_scopetenant_mismatch

{
  "additionalProperties": false,
  "properties": {
    "error": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "enum": [
            "insufficient_scope",
            "tenant_mismatch"
          ],
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "ok": {
      "const": false
    }
  },
  "required": [
    "ok",
    "error"
  ],
  "type": "object"
}

HTTP 404 — Customer not found in the authoritative tenant context.

Códigos de error

customer_not_found

{
  "additionalProperties": false,
  "properties": {
    "error": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "const": "customer_not_found"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "ok": {
      "const": false
    }
  },
  "required": [
    "ok",
    "error"
  ],
  "type": "object"
}

HTTP 429 — Generic rate-limit denial; no numeric limit or retry timing is promised.

Códigos de error

rate_limited

{
  "additionalProperties": false,
  "properties": {
    "error": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "const": "rate_limited"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "ok": {
      "const": false
    }
  },
  "required": [
    "ok",
    "error"
  ],
  "type": "object"
}

HTTP 500 — Sanitized customer state failure.

Códigos de error

customer_state_failedinternal_error

{
  "additionalProperties": false,
  "properties": {
    "error": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "enum": [
            "customer_state_failed",
            "internal_error"
          ],
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "ok": {
      "const": false
    }
  },
  "required": [
    "ok",
    "error"
  ],
  "type": "object"
}

Ejemplos probados

Customer state after purchase

HTTP esperado: 200
Última prueba: 2026-08-11

curl --request GET \
  --url 'https://api.qualth.com/api/customers/{{new_customer_id}}/state' \
  --header 'X-API-Key: {{api_key}}' \
  --header 'X-Tenant-Subdomain: {{tenant_subdomain}}'