openapi: 3.1.0
info:
  title: Partner Tax Documents API
  version: '14'
  description: |
    Tax Documents capture the IRS tax form (W9, W8BEN, W8BENE) that impact.com requires from partners
    before payouts can be issued. Documents are collected through a hosted signing flow provided by
    DocuSign or Comply Exchange.

    Typical workflow:

    1. **Create a tax document** (POST `/TaxDocument`) — returns an iframe URL that the partner opens to fill in and sign the form.
    2. **Complete** (POST `/TaxDocument/Complete`) — called after the user finalizes submission in the Comply Exchange iframe so the system records the outcome. DocuSign uses the `ReturnUrl` callback instead.
    3. **Retrieve** the latest document (GET `/TaxDocument`), a specific document by Id (GET `/TaxDocument/{Id}`), or the full list (GET `/TaxDocuments`) to track status.
  contact:
    name: impact.com Developer Support
    url: https://app.impact.com/secure/help/contact-support.ihtml
servers:
- url: https://api.impact.com
security:
- basicAuth: []
tags:
- name: Tax Documents
  description: Endpoints for creating, completing, and retrieving partner tax documents.
paths:
  /Mediapartners/{AccountSID}/TaxDocument:
    get:
      operationId: retrieveLatestTaxDocument
      tags:
      - Tax Documents
      summary: Retrieve the latest tax document
      description: Returns the most recently saved tax document for the partner account.
      parameters:
      - $ref: '#/components/parameters/AccountSID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxDocument'
      x-codeSamples:
      - lang: Shell
        label: curl
        source: |-
          curl -L \
            --url 'https://api.impact.com/Mediapartners/{AccountSID}/TaxDocument' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
    post:
      operationId: createTaxDocument
      tags:
      - Tax Documents
      summary: Create a tax document
      description: |
        Initiates a new tax document submission. Returns an iframe URL the partner opens to fill in and sign the form. All parameters except `Provider` apply to DocuSign only.
      parameters:
      - $ref: '#/components/parameters/AccountSID'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                DocType:
                  type: string
                  enum:
                  - W9
                  - W8BEN
                  - W8BENE
                  description: The IRS tax form type to collect.
                Id:
                  type: string
                  description: The ID of the account user. Defaults to the first user on the account when omitted.
                ReturnUrl:
                  type: string
                  description: Absolute URL DocuSign uses as the callback after signing.
                Provider:
                  type: string
                  enum:
                  - DOCUSIGN
                  - COMPLY_EXCHANGE
                  description: Required when collecting via Comply Exchange. Defaults to DOCUSIGN.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  Status:
                    type: string
                    description: Outcome status returned by the provider.
                    example: OK
                  Uri:
                    type: string
                    description: API resource path for this tax document.
                    example: /Mediapartners/<AccountSID>/TaxDocuments/224289
                  Email:
                    type: string
                    description: Email address of the user the document was created for.
                    example: hazelnutt@example.com
                  Id:
                    type: string
                    description: Unique identifier for the newly created tax document.
                    example: '224289'
                  UserId:
                    type: string
                    description: ID of the account user the document was created for.
                    example: '12345'
                  Url:
                    type: string
                    description: Iframe URL the partner opens to sign the tax document.
                    example: https://demo.docusign.net/Signing/StartInSession.aspx?t=example
      x-codeSamples:
      - lang: Shell
        label: curl
        source: |-
          curl -L \
            --request POST \
            --url 'https://api.impact.com/Mediapartners/{AccountSID}/TaxDocument' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Content-Type: application/x-www-form-urlencoded' \
            --header 'Accept: */*'
  /Mediapartners/{AccountSID}/TaxDocuments:
    get:
      operationId: listTaxDocuments
      tags:
      - Tax Documents
      summary: List all tax documents
      description: Returns every tax document submitted for the partner account.
      parameters:
      - $ref: '#/components/parameters/AccountSID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  TaxDocuments:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxDocument'
      x-codeSamples:
      - lang: Shell
        label: curl
        source: |-
          curl -L \
            --url 'https://api.impact.com/Mediapartners/{AccountSID}/TaxDocuments' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
  /Mediapartners/{AccountSID}/TaxDocument/{Id}:
    get:
      operationId: retrieveTaxDocumentById
      tags:
      - Tax Documents
      summary: Retrieve a tax document
      description: Returns a specific tax document by its unique Id.
      parameters:
      - $ref: '#/components/parameters/AccountSID'
      - name: Id
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier of the tax document.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxDocument'
        '404':
          description: No tax document exists with the supplied Id.
      x-codeSamples:
      - lang: Shell
        label: curl
        source: |-
          curl -L \
            --url 'https://api.impact.com/Mediapartners/{AccountSID}/TaxDocument/{Id}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
  /Mediapartners/{AccountSID}/TaxDocument/Complete:
    post:
      operationId: completeTaxDocumentSubmission
      tags:
      - Tax Documents
      summary: Complete tax document submission
      description: |
        Records the outcome of a tax document submission collected via the Comply Exchange iframe. Call this immediately after the user finalizes submission in the iframe so the document is recorded as submitted in impact.com. DocuSign signals completion via the `ReturnUrl` callback supplied at Create time instead.
      parameters:
      - $ref: '#/components/parameters/AccountSID'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - id
              - event
              properties:
                id:
                  type: string
                  description: The Id of the tax document being submitted.
                event:
                  type: string
                  enum:
                  - Complete
                  description: The lifecycle event being signalled. Always `Complete`.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  Status:
                    type: string
                    description: Outcome status of the completion call.
                    example: OK
                  Uri:
                    type: string
                    description: API resource path for the completed tax document.
                    example: /Mediapartners/<AccountSID>/TaxDocuments/224289
      x-codeSamples:
      - lang: Shell
        label: curl
        source: |-
          curl -L \
            --request POST \
            --url 'https://api.impact.com/Mediapartners/{AccountSID}/TaxDocument/Complete' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Content-Type: application/x-www-form-urlencoded' \
            --header 'Accept: */*'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your AccountSID as the username and AuthToken as the password.
  parameters:
    AccountSID:
      name: AccountSID
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier for the partner account.
  schemas:
    TaxDocument:
      type: object
      properties:
        Id:
          type: string
          description: Unique identifier of the tax document.
          example: '224289'
        UserId:
          type: string
          description: ID of the account user the document belongs to.
          example: '12345'
        Email:
          type: string
          description: Email address of the user the document belongs to.
          example: hazelnutt@example.com
        Status:
          type: string
          enum:
          - NEW
          - NOT_VERIFIED
          - ACTIVE
          - INACTIVE
          description: Current status of the tax document.
          example: NEW
        EnvelopeId:
          type: string
          description: Unique identifier of the DocuSign envelope (DocuSign provider only).
          example: 47b6c24d-f313-4343-9252-7e477f8a267c
        Type:
          type: string
          nullable: true
          enum:
          - W9
          - W8BEN
          - W8BENE
          description: The IRS tax form type. Empty until the user selects a form in the iframe.
          example: W9
        SubmitDate:
          type: string
          format: date-time
          description: Date and time the tax document was submitted (ISO 8601).
          example: '2024-02-23T04:32:47-08:00'
        UpdateDate:
          type: string
          format: date-time
          description: Date and time the tax document was last updated (ISO 8601).
          example: '2024-02-23T04:32:47-08:00'
        Provider:
          type: string
          enum:
          - DOCUSIGN
          - COMPLY_EXCHANGE
          description: The provider that collected the tax document.
          example: DOCUSIGN
        Uri:
          type: string
          description: API resource path for this tax document.
          example: /Mediapartners/<AccountSID>/TaxDocuments/224289
x-default-client: cURL
