> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcurrent.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Create or update a business record (alias of POST)

> Alias for `POST /businesses`. See that operation for details.



## OpenAPI

````yaml /openapi.yaml put /businesses
openapi: 3.1.0
info:
  title: Current Business Verification API
  version: 1.0.0
  description: >
    The Current API provides programmatic access to Canadian business
    verification services.


    ## Authentication

    All API requests require authentication via API key. Include your key using
    one of these methods:

    - `Authorization: Bearer cur_live_xxxxx` (recommended)

    - `X-API-Key: cur_live_xxxxx`


    ## Rate Limits

    All endpoints are rate limited to **60 requests per minute** per API key.


    Rate limit headers are included in all responses:

    - `X-RateLimit-Limit`: Maximum requests allowed in current window

    - `X-RateLimit-Remaining`: Remaining requests in current window

    - `X-RateLimit-Reset`: Unix timestamp when the rate limit resets


    ## Request IDs

    All responses include an `X-Request-Id` header for traceability.

    You can provide your own via the `X-Request-Id` request header; otherwise
    one is generated automatically.

    Include this ID when contacting support about a specific request.
  contact:
    name: Current Support
    url: https://getcurrent.ca
  license:
    name: Proprietary
servers:
  - url: https://api.getcurrent.ca/v1
    description: Production
security:
  - bearerAuth: []
  - apiKeyHeader: []
tags:
  - name: Search
    description: Business verification search operations
  - name: Pre-fill
    description: Fast typeahead lookup of canonical business candidates
  - name: Generate PDF
    description: PDF report generation
  - name: Business Reports
    description: Business report operations
  - name: Sanctions
    description: Standalone sanctions screening operations
  - name: Verification
    description: Business verification operations
  - name: Businesses
    description: >-
      Business record sync (list/read as a change feed, upsert to keep records
      current)
paths:
  /businesses:
    put:
      tags:
        - Businesses
      summary: Create or update a business record (alias of POST)
      description: Alias for `POST /businesses`. See that operation for details.
      operationId: upsertBusinessPut
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessUpsertRequest'
      responses:
        '200':
          description: Existing business updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessUpsertResponse'
        '201':
          description: New business created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessUpsertResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - bearerAuth: []
        - apiKeyHeader: []
components:
  schemas:
    BusinessUpsertRequest:
      type: object
      description: >
        Fields to create or update. You must supply a match key: either
        `externalId`, or both `jurisdiction` and `registrationNumber`. On
        create, `name` is required. Only the fields you send are written —
        omitted fields are left unchanged. Array fields replace the stored
        value.
      properties:
        externalId:
          type: string
          maxLength: 255
          description: Your internal id (CRM record id). Unique per organization.
        name:
          type: string
          maxLength: 500
        operatingNames:
          type: array
          items:
            type: string
        jurisdiction:
          type: string
          description: Canadian jurisdiction code (normalized server-side)
        registrationNumber:
          type: string
          maxLength: 30
        businessNumber:
          type: string
          maxLength: 30
        entityType:
          type: string
        registryStatus:
          type: string
        incorporationDate:
          type: string
          description: >
            Full incorporation date (YYYY-MM-DD). Use `incorporationYear`
            instead when only the year is known.
        incorporationYear:
          type: integer
          minimum: 1000
          maximum: 9999
          description: >
            Year of incorporation, when only the year is known. Recorded
            separately from `incorporationDate` so a year-only value isn't
            fabricated into a full date.
        registrations:
          type: array
          items:
            type: object
        street:
          type: string
        unit:
          type: string
        city:
          type: string
        province:
          type: string
        postalCode:
          type: string
        country:
          type: string
        addresses:
          type: array
          items:
            type: object
        people:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              role:
                type: string
              roles:
                type: array
                items:
                  type: string
              email:
                type: string
        website:
          type: string
        additionalWebsites:
          type: array
          items:
            type: string
        phoneNumber:
          type: string
        email:
          type: string
        industry:
          type: string
          maxLength: 200
          description: Industry or sector label.
        industryCategory:
          type: string
          maxLength: 200
          description: Higher-level industry category.
        naicsCode:
          type: string
          maxLength: 20
          description: NAICS industry code.
        naicsCodeName:
          type: string
          maxLength: 200
          description: Human-readable NAICS industry description.
        businessDescription:
          type: string
          maxLength: 5000
          description: Free-text description of the business.
        originationDate:
          type: string
          description: YYYY-MM-DD
        notes:
          type: string
        isMonitored:
          type: boolean
        isArchived:
          type: boolean
        expectedUpdatedAt:
          type: string
          format: date-time
          description: >
            Optimistic concurrency guard. If set and a matching record exists,
            the update is rejected with 409 when the record's current
            `updatedAt` differs from this value (i.e. it changed since you last
            read it). Omit to always overwrite. Ignored when a new record is
            created.
    BusinessUpsertResponse:
      type: object
      properties:
        business:
          $ref: '#/components/schemas/Business'
    Business:
      type: object
      description: A business record.
      properties:
        id:
          type: string
          format: uuid
          description: Current's internal id for this business
        externalId:
          type: string
          nullable: true
          description: Your internal id for this business (e.g. CRM record id)
        name:
          type: string
        operatingNames:
          type: array
          items:
            type: string
        jurisdiction:
          type: string
          nullable: true
          description: >-
            Canadian jurisdiction code (AB, BC, MB, NB, NL, NS, NT, NU, ON, PE,
            QC, SK, YT, FED)
        registrationNumber:
          type: string
          nullable: true
        businessNumber:
          type: string
          nullable: true
        entityType:
          type: string
          nullable: true
        sourceEntityType:
          type: string
          nullable: true
        registryStatus:
          type: string
          nullable: true
        incorporationDate:
          type: string
          nullable: true
          description: Full incorporation date (YYYY-MM-DD), when known.
        incorporationYear:
          type: integer
          nullable: true
          description: Year of incorporation, when only the year is known.
        registrations:
          type: array
          items:
            type: object
        address:
          type: object
          properties:
            street:
              type: string
              nullable: true
            unit:
              type: string
              nullable: true
            city:
              type: string
              nullable: true
            province:
              type: string
              nullable: true
            postalCode:
              type: string
              nullable: true
            country:
              type: string
              nullable: true
        addresses:
          type: array
          description: Additional typed address objects
          items:
            type: object
        people:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              roles:
                type: array
                items:
                  type: string
              email:
                type: string
        website:
          type: string
          nullable: true
        additionalWebsites:
          type: array
          items:
            type: string
        phoneNumber:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        industry:
          type: string
          nullable: true
          description: Industry or sector label.
        industryCategory:
          type: string
          nullable: true
          description: Higher-level industry category.
        naicsCode:
          type: string
          nullable: true
          description: NAICS industry code.
        naicsCodeName:
          type: string
          nullable: true
          description: Human-readable NAICS industry description.
        businessDescription:
          type: string
          nullable: true
          description: Free-text description of the business.
        originationDate:
          type: string
          nullable: true
          description: Date (YYYY-MM-DD) the business became your customer
        notes:
          type: string
          nullable: true
        sourceUrls:
          type: array
          items:
            type: string
        isMonitored:
          type: boolean
        isArchived:
          type: boolean
        verificationStatus:
          type: string
          nullable: true
          enum:
            - verified
            - not_verified
            - failed
            - null
        lastVerifiedAt:
          type: string
          format: date-time
          nullable: true
        lastVerificationJobId:
          type: string
          format: uuid
          nullable: true
          description: >
            Batch job that produced the most recent verification. Null when the
            last verification was run individually rather than as part of a
            batch.
        latestVerificationId:
          type: string
          format: uuid
          nullable: true
        hasUnresolvedDiscrepancies:
          type: boolean
        lastSearchedAt:
          type: string
          format: date-time
          nullable: true
        lastSearchJobId:
          type: string
          format: uuid
          nullable: true
          description: >
            Batch job that produced the most recent search. Null when the last
            search was run individually rather than as part of a batch.
        lastScreenedAt:
          type: string
          format: date-time
          nullable: true
          description: When this business was most recently screened.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: >
            Machine-readable error code. Present on every error response.
            Distinct from the per-source `APIError.code` values that appear
            inside a successful response's `meta.errors` object.
          enum:
            - MISSING_API_KEY
            - INVALID_API_KEY
            - REVOKED_API_KEY
            - EXPIRED_API_KEY
            - RATE_LIMITED
            - VALIDATION_ERROR
            - INVALID_JSON
            - NOT_FOUND
            - STALE_WRITE
            - CONFLICT
            - METHOD_NOT_ALLOWED
            - UNAUTHORIZED
            - SERVER_ERROR
            - INTERNAL_ERROR
          example: VALIDATION_ERROR
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: name is required and must be a non-empty string
            code: VALIDATION_ERROR
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing:
              value:
                error: >-
                  Missing API key. Provide via Authorization: Bearer <key> or
                  X-API-Key header.
                code: MISSING_API_KEY
            invalid:
              value:
                error: Invalid API key
                code: INVALID_API_KEY
            revoked:
              value:
                error: API key has been revoked
                code: REVOKED_API_KEY
            expired:
              value:
                error: API key has expired
                code: EXPIRED_API_KEY
    Conflict:
      description: Request conflicts with an existing record
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            staleWrite:
              summary: Optimistic-concurrency conflict (expectedUpdatedAt mismatch)
              value:
                error: Business was modified since expectedUpdatedAt
                code: STALE_WRITE
            conflict:
              summary: Unique-constraint conflict on registration number or external id
              value:
                error: >-
                  Business conflicts with an existing record on registration
                  number or external id
                code: CONFLICT
    RateLimited:
      description: Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          schema:
            type: integer
            example: 0
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          description: Seconds until rate limit resets
          schema:
            type: integer
            example: 60
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Rate limit exceeded. Try again in 60 seconds.
            code: RATE_LIMITED
  headers:
    X-RateLimit-Limit:
      description: Maximum requests per minute
      schema:
        type: integer
        example: 60
    X-RateLimit-Reset:
      description: Unix timestamp when rate limit resets
      schema:
        type: integer
        example: 1702915200
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key as Bearer token: `Authorization: Bearer cur_live_xxxxx`'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key in header: `X-API-Key: cur_live_xxxxx`'

````