> ## Documentation Index > Fetch the complete documentation index at: https://new.cove.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create Consumer > Register a new consumer with PII. The SSN is encrypted at rest using PGP symmetric encryption and is **never returned** in any API response. Uniqueness is enforced per-partner on `email` and `external_id`. ## OpenAPI ````yaml POST /consumers openapi: 3.0.3 info: title: Cove Data Furnishing API description: > A generic data furnishing API that accepts any recurring payment type (rent, child support, alimony, utilities, etc.) and reports it to credit bureaus (Equifax, TransUnion, Experian) in Metro 2 format. ## Authentication All requests require an `x-api-key` header with a valid API key. - `sk_live_*` keys operate in production mode. - `sk_test_*` keys operate in sandbox mode (data is created but never reaches bureaus). ## Amounts All monetary amounts are in **cents** (USD integers). For example, $45.00 = `4500`. ## Dates All date fields use `YYYY-MM-DD` format. ## Integration Guide For a full walkthrough with curl examples, see the [Integration Guide](./integration-guide.md). version: 1.0.0 contact: name: Cove url: https://cove.dev license: name: Proprietary url: https://cove.dev/terms servers: - url: https://vvdufluovypptsnkihyv.supabase.co/functions/v1 description: Current deployment (Supabase) - url: https://furnish.cove.dev/v1 description: Production (coming soon) - url: https://sandbox-furnish.cove.dev/v1 description: Sandbox (coming soon) security: - ApiKeyAuth: [] tags: - name: Consumers description: >- Manage consumer records (PII). Consumers represent the individuals whose payments are being reported to credit bureaus. - name: Tradelines description: >- Manage tradelines — ongoing payment obligations being reported to credit bureaus. Each tradeline belongs to a consumer and tracks a specific payment type. - name: Payments description: >- Report monthly payments against tradelines. Each payment automatically updates the tradeline's account status, balance, and 24-month payment history. - name: Submissions description: >- Track and manage bureau submission status. Submissions are created automatically or via manual trigger. - name: Webhooks description: Webhook event types and payloads delivered to your configured webhook URL. paths: /consumers: post: tags: - Consumers summary: Create a consumer description: | Register a new consumer with PII. The SSN is encrypted at rest using PGP symmetric encryption and is **never returned** in any API response. Uniqueness is enforced per-partner on `email` and `external_id`. operationId: createConsumer requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConsumerCreate' example: first_name: Jane last_name: Doe date_of_birth: '1990-05-15' ssn: 123-45-6789 phone: '+15551234567' email: jane.doe@example.com address: street: 123 Main St city: Austin state: TX postal_code: '73301' country: US external_id: sp-user-001 responses: '201': description: Consumer created content: application/json: schema: $ref: '#/components/schemas/Consumer' example: id: 550e8400-e29b-41d4-a716-446655440000 first_name: Jane last_name: Doe middle_name: null date_of_birth: '1990-05-15' phone: '+15551234567' email: jane.doe@example.com address: street: 123 Main St city: Austin state: TX postal_code: '73301' country: US external_id: sp-user-001 created_at: '2026-02-16T06:16:47.385Z' updated_at: '2026-02-16T06:16:47.385Z' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/AuthenticationError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitedError' '500': $ref: '#/components/responses/InternalError' components: schemas: ConsumerCreate: type: object required: - first_name - last_name - date_of_birth - phone - email - address properties: first_name: type: string minLength: 1 maxLength: 25 last_name: type: string minLength: 1 maxLength: 25 middle_name: type: string maxLength: 25 nullable: true date_of_birth: type: string format: date description: YYYY-MM-DD ssn: type: string nullable: true description: SSN (XXX-XX-XXXX or XXXXXXXXX). Encrypted at rest, never returned. pattern: ^\d{3}-?\d{2}-?\d{4}$ phone: type: string pattern: ^\+\d{10,15}$ description: E.164 format email: type: string format: email address: $ref: '#/components/schemas/Address' external_id: type: string maxLength: 255 nullable: true description: Your internal ID for this consumer Consumer: type: object properties: id: type: string format: uuid first_name: type: string last_name: type: string middle_name: type: string nullable: true date_of_birth: type: string format: date phone: type: string email: type: string address: $ref: '#/components/schemas/Address' external_id: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time Address: type: object required: - street - city - state - postal_code properties: street: type: string maxLength: 100 city: type: string maxLength: 50 state: type: string minLength: 2 maxLength: 2 description: Two-letter state code postal_code: type: string minLength: 3 maxLength: 10 country: type: string default: US minLength: 2 maxLength: 2 description: ISO 3166-1 alpha-2 country code Error: type: object properties: error: type: object required: - code - message - request_id properties: code: type: string enum: - VALIDATION_ERROR - AUTHENTICATION_ERROR - AUTHORIZATION_ERROR - NOT_FOUND - CONFLICT - RATE_LIMITED - INTERNAL_ERROR message: type: string description: Human-readable error description field: type: string description: >- Dot-notation path to the field that caused the error (e.g., address.state). Only present when a specific field is responsible. request_id: type: string format: uuid responses: ValidationError: description: Validation error (400) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: VALIDATION_ERROR message: payment_amount must be a positive integer (cents) field: payment_amount request_id: 4e9024e3-125d-4d08-a392-4fa34f6bda44 AuthenticationError: description: Authentication error (401) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: AUTHENTICATION_ERROR message: Missing x-api-key header request_id: 4e9024e3-125d-4d08-a392-4fa34f6bda44 ConflictError: description: Resource conflict / duplicate (409) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: CONFLICT message: >- A consumer with this email or external_id already exists for this partner request_id: 4e9024e3-125d-4d08-a392-4fa34f6bda44 RateLimitedError: description: Rate limit exceeded (429) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RATE_LIMITED message: Too many requests request_id: 4e9024e3-125d-4d08-a392-4fa34f6bda44 InternalError: description: Internal server error (500) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: An unexpected error occurred request_id: 4e9024e3-125d-4d08-a392-4fa34f6bda44 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: > API key in the format `sk_live_` (production) or `sk_test_` (sandbox). Contact Cove to obtain your API key. ````