> ## Documentation Index > Fetch the complete documentation index at: https://docs.polinate.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a buyer (phantom) and related contacts/locations > Creates a buyer (phantom) with optional contacts and locations; links default item list for the supplier business. Optionally set initial partnership status (defaults to ACTIVE). Idempotent via Idempotency-Key. ## OpenAPI ````yaml openapi.json post /api/v1/buyers openapi: 3.0.3 info: title: Polinate External API version: 1.0.0 description: >- External API for partners and services. Authentication via X-Business-Id and X-API-Key headers. Credentials location: In the Polinate app, navigate to Business Settings → Integrations to find your Business ID and API Key. servers: - url: https://integrations.polinate.ai description: Production security: [] tags: - name: Items description: >- Manage items and item variants. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Buyers description: >- Create buyers and related contacts/locations. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Pricing description: >- Create price lists and entries. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Invoices description: >- List and update invoices. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Orders description: >- Order ingestion. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). paths: /api/v1/buyers: post: tags: - Buyers summary: Create a buyer (phantom) and related contacts/locations description: >- Creates a buyer (phantom) with optional contacts and locations; links default item list for the supplier business. Optionally set initial partnership status (defaults to ACTIVE). Idempotent via Idempotency-Key. operationId: createBuyer parameters: - schema: type: string description: >- Business identifier for external auth. Find in Polinate app → Business Settings → Integrations. example: '{{businessId}}' required: true name: X-Business-Id in: header - schema: type: string description: >- Per-business API key for external auth. Find in Polinate app → Business Settings → Integrations. example: '{{apiKey}}' required: true name: X-API-Key in: header - schema: type: string description: Idempotency key for POST operations example: '{{idempotencyKey}}' required: false name: Idempotency-Key in: header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BuyerCreateRequestPublic' examples: Minimal: summary: Minimal required fields value: buyer: name: Acme Pty Ltd legalName: Acme Pty Ltd Full: summary: All fields with multiple contacts and locations value: buyer: name: Globex Trading Co legalName: Globex Trading Company Pty Ltd primaryEmail: accounts@globex.example primaryPhone: +61 2 9000 0000 partnershipStatus: ACTIVE emails: - email: orders@globex.example contactName: Procurement isPrimary: true isVerified: true verifiedAt: '2025-01-15T10:00:00.000Z' sequence: 1 - email: warehouse@globex.example contactName: Warehouse isPrimary: false isVerified: false sequence: 2 phones: - phone: +61 400 000 001 contactName: Procurement isPrimary: true isVerified: true verifiedAt: '2025-01-15T10:00:00.000Z' sequence: 1 - phone: +61 400 000 002 contactName: Receiving isPrimary: false isVerified: false sequence: 2 locations: - label: Sydney DC type: WAREHOUSE status: ACTIVE addressLine1: 1 George St addressLine2: Dock 3 city: Sydney state: NSW postcode: '2000' country: AU - label: Melbourne Store type: STORE status: ACTIVE addressLine1: 100 Collins St city: Melbourne state: VIC postcode: '3000' country: AU PendingPartnership: summary: Create buyer with PENDING partnership status value: buyer: name: New Prospect Inc legalName: New Prospect Inc primaryEmail: contact@prospect.example partnershipStatus: PENDING responses: '200': description: Created content: application/json: schema: $ref: '#/components/schemas/BuyerCreateResponse' example: success: true phantomId: phm_123 partnershipId: prt_123 '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/StandardError' examples: MissingRequired: summary: Missing required fields value: errorCode: VALIDATION_ERROR message: >- Some information looks incorrect. Please review the highlighted fields. fieldErrors: buyer.name: Required buyer.legalName: Required DuplicateEmails: summary: Duplicate emails value: errorCode: VALIDATION_ERROR message: >- Some information looks incorrect. Please review the highlighted fields. fieldErrors: emails.1.email: Duplicate email addresses are not allowed. DuplicatePhones: summary: Duplicate phones value: errorCode: VALIDATION_ERROR message: >- Some information looks incorrect. Please review the highlighted fields. fieldErrors: phones.1.phone: Duplicate phone numbers are not allowed. DuplicateLocationLabels: summary: Duplicate location labels value: errorCode: VALIDATION_ERROR message: >- Some information looks incorrect. Please review the highlighted fields. fieldErrors: locations.1.label: Duplicate location labels are not allowed. '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/StandardError' example: errorCode: UNAUTHORIZED message: Unauthorized '409': description: Conflict (DB unique constraint) content: application/json: schema: $ref: '#/components/schemas/StandardError' examples: EmailConflict: summary: Buyer email unique value: errorCode: CONFLICT message: This buyer already has that email address. PhoneConflict: summary: Buyer phone unique value: errorCode: CONFLICT message: This buyer already has that phone number. LocationLabelConflict: summary: Location label unique value: errorCode: CONFLICT message: This buyer already has a location with that label. '429': description: Rate limited headers: Retry-After: schema: type: string description: Seconds to wait before retrying content: application/json: schema: $ref: '#/components/schemas/StandardError' examples: BurstyTraffic: summary: Too many requests value: errorCode: RATE_LIMITED message: >- You’re sending requests too quickly. Please try again shortly. '500': description: Default item list missing or duplicated content: application/json: schema: $ref: '#/components/schemas/StandardError' example: errorCode: INTERNAL_ERROR message: Default item list missing or duplicated components: schemas: BuyerCreateRequestPublic: type: object properties: buyer: type: object properties: name: type: string legalName: type: string primaryEmail: type: string format: email primaryPhone: type: string required: - name - legalName partnershipStatus: type: string enum: - DECLINED - PENDING - REVIEW - ACTIVE - PAUSED - SUSPENDED - EXPIRED - TERMINATED phones: type: array items: type: object properties: phone: type: string description: Must be unique per buyer contactName: type: string isPrimary: type: boolean isVerified: type: boolean verifiedAt: type: string format: date-time sequence: type: number required: - phone default: [] emails: type: array items: type: object properties: email: type: string format: email description: Must be unique per buyer contactName: type: string isPrimary: type: boolean isVerified: type: boolean verifiedAt: type: string format: date-time sequence: type: number required: - email default: [] locations: type: array items: type: object properties: label: type: string description: Must be unique per buyer type: type: string enum: - WAREHOUSE - DISTRIBUTION - STORE status: type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED addressLine1: type: string addressLine2: type: string city: type: string state: type: string postcode: type: string country: type: string required: - label - type - status - addressLine1 - city - state - postcode - country default: [] required: - buyer example: buyer: name: Acme Pty Ltd legalName: Acme Pty Ltd BuyerCreateResponse: type: object properties: success: type: boolean phantomId: type: string partnershipId: type: string required: - success - phantomId - partnershipId StandardError: type: object properties: errorCode: type: string message: type: string fieldErrors: type: object additionalProperties: type: string required: - errorCode - message ````