Boardwalk Enrichment API

openapi: 3.2.0
info:
  title: Boardwalkai Com Enrichment API
  version: '2026-09-16'
  contact:
    name: Boardwalk Support
    email: support@boardwalkai.com
    url: https://boardwalkai.com
  description: 'Operations tagged Enrichment across 2 of this provider''s published API definitions: boardwalkai-com-openapi.json, boardwalkai-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.boardwalkai.com/api/v1
  description: Production
- url: http://localhost:8000/api/v1
  description: Local development
security:
- bearerAuth: []
tags:
- name: Enrichment
  description: 'Find contact info. County, State, and National: 1 credit per project the first time this account receives email or phone. Standalone API Only: included on records already purchased. Empty lookups cost nothing.'
paths:
  /enrichments:
    post:
      tags:
      - Enrichment
      summary: 'Find contact info: 1 credit per newly unlocked project'
      description: 'Queue Find Contact Info for project ids. The pipeline runs asynchronously; poll `GET /enrichments/{id}` for progress.


        **Cost: 1 credit per project** the first time this account receives a usable external person email, phone, or personal LinkedIn profile. Names and company links alone cost nothing. API Only includes enrichment on purchased records; trials use their separate five-project grant. A project this pool has already unlocked is skipped and is free to re-read. The maximum contact cost is held when queued. On completion, only qualifying delivery is charged and unused credits are released. Read contactBilling for the cumulative job receipt; polling meta.creditsUsed stays 0. A request that would exceed the remaining credit balance is refused with `402` and nothing queued.


        IDs whose contacts were already found for this pool, or attempted recently, are skipped as `skipped.alreadyEnriched`. When every ID is skipped the response is `200` with `status: nothing_to_enrich` and no job.


        Enrichment runs about a minute per lead at roughly two leads per project, so a large batch takes hours: a 100-project job is a multi-hour job. `estimatedCompletion` is a best-effort **estimate for polling cadence, not a deadline**. Up to 250 project IDs per job.


        **`Idempotency-Key` is required.** Re-sending the same key answers with the job the key already created and does not charge again.'
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
        description: Required. An opaque string (up to 255 characters of `A-Za-z0-9_.:-`) that makes a retry replay the same job instead of submitting a second one.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - projectIds
              properties:
                projectIds:
                  type: array
                  items:
                    type: integer
                  description: Projects to find contact info for.
            example:
              projectIds:
              - 10754108
              - 10754109
      responses:
        '202':
          description: Job queued. `accepted` lists the IDs the job will attempt; `skipped` explains every ID it will not, and `pollUrl` is where progress lives.
          content:
            application/json:
              schema:
                type: object
                properties:
                  enrichmentJobId:
                    type:
                    - integer
                    - 'null'
                  contactBilling:
                    $ref: '#/components/schemas/ContactBillingReceipt'
                  status:
                    type: string
                    enum:
                    - queued
                    - nothing_to_enrich
                  accepted:
                    type: array
                    items:
                      type: integer
                  skipped:
                    type: object
                    properties:
                      notPurchased:
                        type: array
                        items:
                          type: integer
                      alreadyEnriched:
                        type: array
                        items:
                          type: integer
                  estimatedCompletion:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    description: Best-effort completion estimate from the measured enrichment rate (~2 leads/project, ~1 minute/lead). An estimate, not a deadline, so keep polling past it.
                  pollUrl:
                    type:
                    - string
                    - 'null'
                  allowance:
                    $ref: '#/components/schemas/EnrichmentAllowance'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '200':
          description: 'Every ID was skipped: `status: nothing_to_enrich`, no job queued, no allowance consumed.'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '400':
          description: Missing `Idempotency-Key` header (param `Idempotency-Key`), missing/invalid projectIds, or more than the per-job cap. Nothing is queued.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Plan has no enrichment entitlement, or the monthly enrichment allowance would be exceeded (`enrichment_allowance_exceeded`, with used/limit/resets in details). Nothing is queued.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '501':
          $ref: '#/components/responses/EnrichmentUnavailable'
        '503':
          description: 'Enrichment temporarily unavailable, or the purchased-projects ledger could not be read (`enrichment_ledger_unavailable`). Fails closed: nothing is queued.'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
      operationId: postEnrichments
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
  /enrichments/{id}:
    get:
      tags:
      - Enrichment
      summary: Poll an enrichment job (free)
      description: 'Progress for a submitted enrichment job: `"processed": 57, "requested": 100, "pending": 43` while running, `status: completed` when done. `found` counts the projects where contacts were found so far. Free to poll. Jobs belong to the credit pool that queued them; anyone else''s job is a 404.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Job state and progress counts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  enrichmentJobId:
                    type: integer
                  contactBilling:
                    $ref: '#/components/schemas/ContactBillingReceipt'
                  creditsCharged:
                    type:
                    - integer
                    - 'null'
                  status:
                    type: string
                    description: queued | running | completed | failed
                  requested:
                    type: integer
                  processed:
                    type: integer
                  found:
                    type: integer
                  pending:
                    type: integer
                  allowanceUsed:
                    type:
                    - integer
                    - 'null'
                  allowanceRemaining:
                    type:
                    - integer
                    - 'null'
                  notAttempted:
                    type:
                    - integer
                    - 'null'
                    description: 'On a completed job the per-request ceilings stopped early: how many requested projects were never tried (= requested − processed). Those projects were not counted against the monthly allowance, and resubmitting exactly those ids is free to try. Absent when every requested project was attempted.'
                  note:
                    type:
                    - string
                    - 'null'
                    description: Human-readable companion to `notAttempted`, present in the same case.
                  error:
                    type:
                    - string
                    - 'null'
                    description: Why the job failed, when `status` is `failed` (e.g. enrichment was disabled before the job ran; the allowance is refunded). Null otherwise.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No such enrichment job on this account.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      operationId: getEnrichmentsById
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
components:
  schemas:
    EnrichmentAllowance:
      type: object
      description: 'The monthly enrichment allowance: the meter behind the free find-contact-info flow. `limit` null means the plan carries no explicit cap. The same meter appears on `GET /account/credits` under `data.enrichment`, where it is spelled `monthlyAttemptsLimit` / `attemptsUsed` / `attemptsRemaining` / `resetsAt`; and on `GET /enrichments/{id}` as the two flat counters `allowanceUsed` and `allowanceRemaining`.'
      properties:
        used:
          type: integer
        limit:
          type:
          - integer
          - 'null'
        remaining:
          type:
          - integer
          - 'null'
        resetsAt:
          type: string
          format: date-time
    ApiError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - param
          - details
          - docsUrl
          - requestId
          properties:
            code:
              type: string
              description: Stable machine-readable code. Branch on this value.
            message:
              type: string
              description: Human-readable explanation. Do not parse it.
            param:
              type:
              - string
              - 'null'
              description: The offending input parameter, when applicable.
            details:
              type: object
              description: Structured, camelCase context. Always an object, empty when there is no context.
              additionalProperties: true
            docsUrl:
              type: string
              format: uri
              description: Documentation for this exact error code.
            requestId:
              type: string
              description: Matches X-Request-Id and the server-side usage/log record.
          additionalProperties: false
      additionalProperties: false
    ContactBillingReceipt:
      type:
      - object
      - 'null'
      description: Cumulative job billing. meta.creditsUsed on polling remains zero. Only a newly unlocked project delivering an external person email, phone, or personal LinkedIn qualifies. Company links and names alone are free.
      properties:
        attemptKey:
          type: string
        reserved:
          type: integer
        charged:
          type: integer
        released:
          type: integer
        refunded:
          type: integer
        qualifyingProjects:
          type: integer
        newlyUnlockedProjects:
          type: integer
        alreadyUnlockedProjects:
          type: integer
        recordReserved:
          type: integer
        recordCharged:
          type: integer
        recordReleased:
          type: integer
        settled:
          type: boolean
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: missing_api_key
              message: 'API key is required. Include it as Authorization: Bearer bwk_live_... or X-API-Key: bwk_live_...'
              param: null
              details: {}
              docsUrl: https://boardwalkai.com/docs/api/errors#missing_api_key
              requestId: req_01K1QF3M0000EXAMPLE0001
      headers:
        X-Boardwalk-Schema-Version:
          $ref: '#/components/headers/BoardwalkSchemaVersion'
    IdempotencyConflict:
      description: 'The `Idempotency-Key` on this request conflicts with an earlier one. `error.code` says which:


        * `idempotency_key_reuse`: this key was already used for a **different** request. `details.originalEndpoint` and `details.originalCreatedAt` name the request it belongs to. Mint a new key per distinct request; reuse a key only to retry the request it was minted for.

        * `idempotency_in_flight`: the original request with this key is still running. Retry in a moment to receive its result; you will not be charged twice. Carries a `Retry-After` header, echoed as `details.retryAfterSeconds`.


        Both name `Idempotency-Key` in `error.param`. Nothing is delivered and nothing is charged.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: idempotency_key_reuse
              message: This Idempotency-Key was already used for a different request. Generate a new key for each distinct request; reuse a key only to retry the request it was minted for.
              param: Idempotency-Key
              details:
                originalEndpoint: api_v1_projects_search
                originalCreatedAt: '2026-08-27T14:02:11+00:00'
              docsUrl: https://boardwalkai.com/docs/api/errors#idempotency_key_reuse
              requestId: req_01K1QF3M0000EXAMPLE0001
      headers:
        X-Boardwalk-Schema-Version:
          $ref: '#/components/headers/BoardwalkSchemaVersion'
    RateLimitExceeded:
      description: 'Too many requests in the trailing 60 seconds. Limits are per API key: 60 requests per minute on any paid plan, 10 per minute on a free-trial key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 also carries Retry-After. Before authentication, a missing credential uses a 10-per-minute source-IP bucket and an unknown or unusable Boardwalk-shaped key uses its own 10-per-minute credential-digest bucket.'
      headers:
        X-Boardwalk-Schema-Version:
          $ref: '#/components/headers/BoardwalkSchemaVersion'
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Requests allowed per minute for the applicable key or pre-authentication bucket.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests left in the current window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix timestamp at which the window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: rate_limit_exceeded
              message: Rate limit of 60 requests per minute exceeded. Retry in 12 seconds.
              param: null
              details:
                retryAfterSeconds: 12
              docsUrl: https://boardwalkai.com/docs/api/errors#rate_limit_exceeded
              requestId: req_01K1QF3M0000EXAMPLE0001
    EnrichmentUnavailable:
      description: Find Contact Info is compiled in but not switched on for this environment (`501 enrichment_unavailable`). Drop `include=contacts` and retry. Nothing was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: enrichment_unavailable
              message: Finding contact info is not switched on yet.
              param: include
              details: {}
              docsUrl: https://boardwalkai.com/docs/api/errors#enrichment_unavailable
              requestId: req_01K1QF3M0000EXAMPLE0001
      headers:
        X-Boardwalk-Schema-Version:
          $ref: '#/components/headers/BoardwalkSchemaVersion'
  headers:
    BoardwalkSchemaVersion:
      description: The date-stamped response contract version. Present on every public v1 response.
      schema:
        type: string
        example: '2026-09-16'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Boardwalk API key. Keys you create under Settings → API are prefixed `bwk_live_` and read the production corpus against your plan or free-trial balance. `bwk_test_` is reserved for a separate sandbox environment that is not serving data yet. Pre-rename `csk_` keys are accepted indefinitely. Create and rotate keys at https://boardwalkai.com/profile/api.
x-refined-from:
- boardwalkai-com-openapi.json
- boardwalkai-com-openapi.yml