Abound W-8BEN API

openapi: 3.1.0
info:
  title: Abound API - v4 1099-INT W-8BEN API
  version: '4'
  description: 'Abound was a US tax-compliance API for platforms and marketplaces: W-9 / W-8BEN / W-8BEN-E collection, real-time TIN verification against the IRS, and generation, filing, correction, voiding and physical mailing of Form 1099-NEC, 1099-MISC, 1099-K and 1099-INT with federal and state tax authorities.


    NOTE: This document is a mechanical conversion of the first-party Fern API Definition that Abound shipped inside its official npm package @withabound/node-sdk (v6.0.68). Abound was acquired and the service has been retired: the withabound.com DNS zone is fully de-delegated and the API hosts no longer resolve. This spec is preserved as a historical record of the API surface.'
  x-status: retired
servers:
- url: https://production-api.withabound.com
  description: Production (retired - host no longer resolves)
- url: https://sandbox-api.withabound.com
  description: Sandbox (retired - host no longer resolves)
security:
- bearerAuth: []
tags:
- name: W-8BEN
paths:
  /v4/documents/w-8ben:
    get:
      operationId: formW8benList
      tags:
      - W-8BEN
      summary: List all W-8BEN documents
      description: Returns a list of W-8BEN documents.
      parameters:
      - name: page
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Page'
      - name: payeeTinFingerprint
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PayeeTinFingerprint'
      - name: payeeForeignTinFingerprint
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PayeeForeignTinFingerprint'
      - name: userId
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/UserId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/W8BenSchema'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequestSchema'
              example:
                errors:
                - field: metadata.key
                  message: Expected metadata.key to be of type string, but received number
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultErrorSchema'
              example:
                message: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultErrorSchema'
              example:
                message: Not Found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultErrorSchema'
              example:
                message: Internal Server Error
    post:
      operationId: formW8benCreate
      tags:
      - W-8BEN
      summary: Create a W-8BEN
      description: Creates a W-8BEN document and, if present, subsequently kicks off a TIN Verification. A TIN Verification will only kickoff if the name and TIN combo has not been seen before.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/W8BenRequestSchema'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/W8BenSchema'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequestSchema'
              example:
                errors:
                - field: metadata.key
                  message: Expected metadata.key to be of type string, but received number
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultErrorSchema'
              example:
                message: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultErrorSchema'
              example:
                message: Not Found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultErrorSchema'
              example:
                message: Internal Server Error
  /v4/documents/w-8ben/{documentId}:
    get:
      operationId: formW8benRetrieve
      tags:
      - W-8BEN
      summary: Retrieve a W-8BEN
      description: Retrieves the details of an existing W-8BEN document.
      parameters:
      - name: documentId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/DocumentId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/W8BenSchema'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequestSchema'
              example:
                errors:
                - field: metadata.key
                  message: Expected metadata.key to be of type string, but received number
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultErrorSchema'
              example:
                message: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultErrorSchema'
              example:
                message: Not Found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultErrorSchema'
              example:
                message: Internal Server Error
components:
  schemas:
    W8BenBeneficialOwnerSchema:
      allOf:
      - $ref: '#/components/schemas/W8BenBeneficialOwnerRequestSchema'
      - type: object
        properties:
          tinFingerprint:
            $ref: '#/components/schemas/TinFingerprint'
          tinType:
            $ref: '#/components/schemas/TinTypeEnum'
          tinVerificationId:
            $ref: '#/components/schemas/TinVerificationId'
          tinVerificationStatus:
            $ref: '#/components/schemas/TinVerificationStatusEnum'
          foreignTinFingerprint:
            $ref: '#/components/schemas/ForeignTinFingerprint'
    W8BenBeneficialOwnerRequestSchema:
      type: object
      properties:
        name:
          type: string
          description: The payee's legal name (first + last).
        citizenshipCountry:
          type: string
          description: The payee's country of citizenship adhering to `ISO 3166-2` standards.
          minLength: 2
          maxLength: 2
        tin:
          type: string
          description: The payee's US tax identification number, commonly referred to as a TIN. No hyphens. Numerical digits only. Alternatively, you may pass the corresponding `tinFingerprint`.
          minLength: 9
          maxLength: 9
        foreignTin:
          type: string
          description: The payee's foreign tax identifying number, commonly referred to as a FTIN. No hyphens. Alphanumeric digits only. Alternatively, you may pass the corresponding `foreignTinFingerprint`.
        dateOfBirth:
          type: string
          description: The date, in `YYYY-MM-DD` format, the payee was born on.
          pattern: ^\d{4}-\d{2}-\d{2}$
        permanentResidenceAddress:
          allOf:
          - $ref: '#/components/schemas/ForeignAddressSchema'
          description: Permanent residence address (street, apt. or suite no., or rural route). Do not use a P.O. box or in-care-of address.
        mailingAddress:
          allOf:
          - $ref: '#/components/schemas/AddressSchema'
          description: The mailing address. Only include if different from the permanent residence address.
      required:
      - citizenshipCountry
      - dateOfBirth
      - name
      - permanentResidenceAddress
      description: The payee (beneficial owner) completing the document.
    TaxTreatyBenefitsSchema:
      type: object
      properties:
        residentCountry:
          type: string
          description: The foreign country, adhering to `ISO 3166-2` standards, the payee is claiming treaty benefits as a resident with which the United States has an income tax treaty for payments subject to withholding under chapter 3 or under section 1446(a) or (f).
          minLength: 2
          maxLength: 2
        claimedProvision:
          type: string
          description: The article and paragraph of the tax treaty that cite the provisions the payee is claiming. Max 20 characters.
          maxLength: 20
        rateOfWithholding:
          type: number
          description: The decimal percentage rate of withholding the tax treaty allows by default. Rates are subject to validation and approval by the Payer.
        incomeCode:
          allOf:
          - $ref: '#/components/schemas/TaxTreatyIncomeCodeEnum'
          description: The code of the income associated with the claimed rate of withholding.
        incomeType:
          type: string
          const: SERVICES
          description: The type of income associated with the claimed rate of withholding.
        additionalConditions:
          type: string
          description: The additional conditions the payee is claiming under the cited tax treaty.
      required:
      - claimedProvision
      - incomeCode
      - incomeType
      - rateOfWithholding
      - residentCountry
      description: The tax treaty benefits the payee is claiming.
    W8BenFormFieldsSchema:
      type: object
      properties:
        taxClassification:
          type: string
          const: INDIVIDUAL
          description: The tax classification of the payee.
        isForeignTinNotRequired:
          type: boolean
          description: Pass true if a foreign TIN is not legally required. Otherwise false.
        taxTreatyBenefits:
          allOf:
          - $ref: '#/components/schemas/TaxTreatyBenefitsSchema'
          description: The tax treaty benefits the payee is claiming.
        referenceNumbers:
          type: array
          items:
            type: string
          description: The reference numbers to list on this W-8BEN. Two reference numbers are allowed. Max 20 characters each.
        isCertified:
          type: boolean
          description: Pass true if the payee has certified the W-8BEN. Otherwise false.
        electronicSignature:
          allOf:
          - $ref: '#/components/schemas/ElectronicSignatureOfPayeeSchema'
          description: The electronic signature of the payee.
      required:
      - isCertified
      - taxClassification
    TaxTreatyAboundCodeEnum:
      type: string
      enum:
      - AU_17_INDEPENDENT_PERSONAL_SERVICES
      - AU_18_DEPENDENT_PERSONAL_SERVICES
      - AU_42_PUBLIC_ENTERTAINMENT
      - CA_17_INDEPENDENT_PERSONAL_SERVICES
      - CA_18_DEPENDENT_PERSONAL_SERVICES
      - CA_42_PUBLIC_ENTERTAINMENT
      - CN_17_INDEPENDENT_PERSONAL_SERVICES
      - CN_18_DEPENDENT_PERSONAL_SERVICES
      - CN_42_PUBLIC_ENTERTAINMENT
      - GB_17_INDEPENDENT_PERSONAL_SERVICES
      - GB_18_DEPENDENT_PERSONAL_SERVICES
      - GB_42_PUBLIC_ENTERTAINMENT
      - IL_16_SCHOLARSHIP_AND_FELLOWSHIP_GRANT
      - IL_17_INDEPENDENT_PERSONAL_SERVICES
      - IL_18_DEPENDENT_PERSONAL_SERVICES
      - IL_42_PUBLIC_ENTERTAINMENT
      - IN_17_INDEPENDENT_PERSONAL_SERVICES
      - IN_18_DEPENDENT_PERSONAL_SERVICES
      - IN_42_PUBLIC_ENTERTAINMENT
      - MX_17_INDEPENDENT_PERSONAL_SERVICES
      - MX_18_DEPENDENT_PERSONAL_SERVICES
      - MX_42_PUBLIC_ENTERTAINMENT
      description: The tax treaty code the payee is claiming.
    TinTypeEnum:
      type: string
      enum:
      - INDIVIDUAL
      - BUSINESS
      description: The type of the TIN. `INDIVIDUAL` refers to SSNs, ITINs, or ATINs. While `BUSINESS` refers to EINs.
    ForeignTinFingerprint:
      type: string
      description: The unique token that points to a foreign TIN.
    Page:
      type: integer
      description: The specific page of results you're requesting. Responses are limited to a maximum of 100 records.
    ElectronicSignatureOfPayeeSchema:
      type: object
      properties:
        signature:
          type: string
          description: The signature of the payee.
        printedName:
          type: string
          description: The printed name of the payee.
        signedAt:
          type: string
          format: date-time
          description: The date and time in `ISO 8601` format of the signature.
        ipAddress:
          type: string
          description: The IP address of the payee when signing this document.
      required:
      - ipAddress
      - printedName
      - signature
      - signedAt
      description: The electronic signature of the payee.
    TinFingerprint:
      type: string
      description: Your unique token that points to a TIN.
    TaxTreatyIncomeCodeEnum:
      type: string
      enum:
      - '16'
      - '17'
      - '18'
      - '42'
    ErrorBadRequestSchema:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorBadRequestSchemaErrorsItem'
          description: The error message(s) associated with the response status code.
      required:
      - errors
    PayeeForeignTinFingerprint:
      type: string
      description: Filters the list of documents based on the `payee.foreignTinFingerprint` field.
    UserId:
      type: string
      description: The unique identifier for a single end-user of your application.
    ForeignAddressSchema:
      type: object
      properties:
        address:
          type: string
          description: The legal address.
        address2:
          type: string
          description: The second part of the legal address, such as an apartment or suite number.
        city:
          type: string
          description: The city associated with the street address.
        state:
          type: string
          description: The province associated with the street address.
        postalCode:
          type: string
          description: The foreign postal code associated with the street address.
        country:
          type: string
          description: The country adhering to `ISO 3166-2` standards.
          minLength: 2
          maxLength: 2
      required:
      - address
      - country
    TinVerificationStatusEnum:
      type: string
      enum:
      - MATCH
      - MISMATCH
      - PENDING
      description: The status of the TIN Verification.
    W8BenFormFieldsRequestSchema:
      type: object
      properties:
        isForeignTinNotRequired:
          type: boolean
          description: Pass true if a foreign TIN is not legally required. Otherwise false.
        taxTreatyCode:
          allOf:
          - $ref: '#/components/schemas/TaxTreatyAboundCodeEnum'
          description: Abound's shorthand code for the particular US tax treaty the payee is claiming.
        referenceNumbers:
          type: array
          items:
            type: string
          description: The reference numbers to list on this W-8BEN. Two reference numbers are allowed. Max 20 characters each.
        isCertified:
          type: boolean
          description: Pass true if the payee has certified the W-8BEN. Otherwise false.
        electronicSignature:
          allOf:
          - $ref: '#/components/schemas/ElectronicSignatureOfPayeeSchema'
          description: The electronic signature of the payee.
      required:
      - isCertified
    AddressSchema:
      type: object
      properties:
        address:
          type: string
          description: The legal address.
        address2:
          type: string
          description: The second part of the legal address, such as an apartment or suite number.
        city:
          type: string
          description: The city associated with the street address. Required if `country` is `US`.
        state:
          type: string
          description: The two-letter character code for this state or US territory (`CA` for California, `ME` for Maine, `PR` for Puerto Rico). Required if `country` is `US`. If foreign, use the province.
        postalCode:
          type: string
          description: The postal code associated with the street address. Required to be a 5-digit numerical value if `country` is `US`. If foreign, use the foreign postal code.
        country:
          type: string
          description: The country adhering to `ISO 3166-2` standards.
          minLength: 2
          maxLength: 2
      required:
      - address
      - country
    DocumentId:
      type: string
      description: The unique identifier for an existing document.
    PayeeTinFingerprint:
      type: string
      description: Filters the list of documents based on the `payee.tinFingerprint` field.
    DefaultErrorSchema:
      type: object
      properties:
        message:
          type: string
          description: The error message associated with the response status code.
      required:
      - message
    W8BenSchema:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the W-8BEN document.
        createdAt:
          type: string
          format: date-time
          description: The date and time in `ISO 8601` format when the W-8BEN document was created.
        expiresAt:
          type: string
          format: date-time
          description: The date and time in `ISO 8601` format when the W-8BEN is expired and requires re-collection.
        url:
          type: string
          description: The URL to the W-8BEN document.
        payee:
          $ref: '#/components/schemas/W8BenBeneficialOwnerSchema'
        formFields:
          $ref: '#/components/schemas/W8BenFormFieldsSchema'
        userId:
          $ref: '#/components/schemas/UserId'
      required:
      - createdAt
      - expiresAt
      - formFields
      - id
      - payee
      - url
      examples:
      - id: documentId_samplexEM8PRV7sh
        createdAt: '2024-01-01T00:00:00.000Z'
        expiresAt: '2029-01-01T00:00:00.000Z'
        url: https://tax-documents-sandbox.s3.us-west-2.amazonaws.com/FORM-W-8BEN.pdf
        payee:
          name: Ada Lovelace
          citizenshipCountry: GB
          dateOfBirth: '1982-12-10'
          permanentResidenceAddress:
            address: 43 Hilly Fields
            address2: Suite 32
            city: Lewisham
            state: London
            postalCode: SE13 7JN
            country: GB
          mailingAddress:
            address: 256 Byron Street
            address2: Suite 32
            city: Palo Alto
            postalCode: '94306'
            state: CA
            country: US
          tin: '*******00'
          tinType: INDIVIDUAL
          tinFingerprint: tinFingerprint_samplehy2BWO6JJG
          tinVerificationId: tinVerificationId_sample41SD71AV8f
          tinVerificationStatus: MATCH
          foreignTin: '*******6C'
          foreignTinFingerprint: tinFingerprint_sampleanXo4V9nL9
        formFields:
          taxClassification: INDIVIDUAL
          isForeignTinNotRequired: false
          taxTreatyBenefits:
            residentCountry: GB
            claimedProvision: '7'
            rateOfWithholding: 0
            incomeCode: '17'
            incomeType: SERVICES
            additionalConditions: Independent personal services performed in the US
          referenceNumbers:
          - '123456789'
          isCertified: true
          electronicSignature:
            signature: Ada Lovelace
            printedName: Ada Lovelace
            signedAt: '2024-01-01T00:00:00.000Z'
            ipAddress: 127.0.0.1
    TinVerificationId:
      type: string
      description: The unique identifier for the TIN Verification.
    W8BenRequestSchema:
      type: object
      properties:
        payee:
          $ref: '#/components/schemas/W8BenBeneficialOwnerRequestSchema'
        formFields:
          $ref: '#/components/schemas/W8BenFormFieldsRequestSchema'
        userId:
          $ref: '#/components/schemas/UserId'
      required:
      - formFields
      - payee
      examples:
      - payee:
          name: Ada Lovelace
          citizenshipCountry: GB
          tin: '000000000'
          foreignTin: DQ123456C
          dateOfBirth: '1982-12-10'
          permanentResidenceAddress:
            address: 43 Hilly Fields
            address2: Suite 32
            city: Lewisham
            state: London
            postalCode: SE13 7JN
            country: GB
          mailingAddress:
            address: 256 Byron Street
            address2: Suite 32
            city: Palo Alto
            postalCode: '94306'
            state: CA
            country: US
        formFields:
          isForeignTinNotRequired: false
          taxTreatyCode: GB_17_INDEPENDENT_PERSONAL_SERVICES
          referenceNumbers:
          - '123456789'
          isCertified: true
          electronicSignature:
            signature: Ada Lovelace
            printedName: Ada Lovelace
            signedAt: '2024-01-01T00:00:00.000Z'
            ipAddress: 127.0.0.1
    ErrorBadRequestSchemaErrorsItem:
      type: object
      properties:
        field:
          type: string
          description: The field that caused the error.
        message:
          type: string
          description: The error message associated with the field.
      required:
      - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token. The token is the concatenation of your Abound appId and appSecret separated by a period, e.g. `appId_xxx.appSecret_yyy`.