impact.com Agency API

openapi: 3.1.0
info:
  title: Agency API — Advertisers
  version: "3.0"

servers:
  - url: https://api.impact.com
    description: Production

tags:
  - name: Advertisers
    description: Advertiser accounts managed by this agency.

paths:
  /Agencies/{AccountSID}/Advertisers:
    get:
      operationId: listAdvertisers
      summary: List all advertisers
      description: |-
        Returns a list of all advertisers associated with your agency account.

        Each result includes full account details — contact information, billing setup, organization details, and a pre-authenticated `RestAccountURL` for making direct API calls to each advertiser's account.
      tags:
        - Advertisers
      parameters:
        - name: AccountSID
          in: path
          required: true
          description: Your Agency Account SID.
          schema:
            type: string
          example: IRq8mWJybvoQ1020978kbj7am8zzM2dBL1
      responses:
        "200":
          description: A list of advertisers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Advertiser"
              example:
                - Id: "1048291"
                  Name: "Nutt & Co. Outdoors"
                  Description: "Premium outdoor gear and adventure accessories."
                  State: "ACTIVE"
                  Website: "www.nuttandco.com"
                  AddressLine1: "100 Commerce Drive"
                  AddressLine2: "Suite 200"
                  City: "Austin"
                  CountryState: "TX"
                  PostalCode: "78701"
                  Country: "US"
                  IndirectTaxJurisdiction: ""
                  VatRegistered: "false"
                  OrganizationType: "CORP"
                  TaxId: "XXXXX4832"
                  IndirectTaxNumber: ""
                  Timezone: "America/Chicago"
                  Currency: "USD"
                  PhoneNumber: "15125550191"
                  DateCreated: "2021-03-15T09:22:11-07:00"
                  FinancialSetup: "BILLED_BY_IR"
                  AgencyOfRecord: "true"
                  AccountManager: "Carrie Oakey"
                  RestAccountURL: "IRxxxxxxxxxxxxxxxxx1:xxxxxxxxxxxxxxxxxxxxxxxx@api.impactradius.com/Advertisers/IRxxxxxxxxxxxxxxxxx1"
                  Uri: "/Agencies/IRq8mWJybvoQ1020978kbj7am8zzM2dBL1/Advertisers/1048291"
        "401":
          description: Unauthorized. Check that your Account SID and Auth Token are correct.

  /Agencies/{AccountSID}/Advertisers/{AdvertiserId}:
    get:
      operationId: getAdvertiser
      summary: Get an advertiser
      description: Returns the full details of a single advertiser account by its numeric ID.
      tags:
        - Advertisers
      parameters:
        - name: AccountSID
          in: path
          required: true
          description: Your Agency Account SID.
          schema:
            type: string
          example: IRq8mWJybvoQ1020978kbj7am8zzM2dBL1
        - name: AdvertiserId
          in: path
          required: true
          description: The numeric ID of the advertiser to retrieve. Use the `Id` field from the List Advertisers response.
          schema:
            type: string
          example: "1048291"
      responses:
        "200":
          description: The advertiser object.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Advertiser"
              example:
                Id: "1048291"
                Name: "Nutt & Co. Outdoors"
                Description: "Premium outdoor gear and adventure accessories."
                State: "ACTIVE"
                Website: "www.nuttandco.com"
                AddressLine1: "100 Commerce Drive"
                AddressLine2: "Suite 200"
                City: "Austin"
                CountryState: "TX"
                PostalCode: "78701"
                Country: "US"
                IndirectTaxJurisdiction: ""
                VatRegistered: "false"
                OrganizationType: "CORP"
                TaxId: "XXXXX4832"
                IndirectTaxNumber: ""
                Timezone: "America/Chicago"
                Currency: "USD"
                PhoneNumber: "15125550191"
                DateCreated: "2021-03-15T09:22:11-07:00"
                FinancialSetup: "BILLED_BY_IR"
                AgencyOfRecord: "true"
                AccountManager: "Carrie Oakey"
                RestAccountURL: "IRxxxxxxxxxxxxxxxxx1:xxxxxxxxxxxxxxxxxxxxxxxx@api.impactradius.com/Advertisers/IRxxxxxxxxxxxxxxxxx1"
                Uri: "/Agencies/IRq8mWJybvoQ1020978kbj7am8zzM2dBL1/Advertisers/1048291"
        "401":
          description: Unauthorized. Check that your Account SID and Auth Token are correct.
        "404":
          description: Advertiser not found. Verify that the AdvertiserId belongs to an advertiser managed by this agency.

components:
  schemas:
    Advertiser:
      type: object
      description: An advertiser account managed through your agency.
      properties:
        Id:
          type: string
          description: The unique numeric identifier for the advertiser account.
          example: "1048291"
        Name:
          type: string
          description: The advertiser's business or brand name as registered on impact.com.
          example: "Nutt & Co. Outdoors"
        Description:
          type: string
          description: A free-text description of the advertiser. May be an empty string if none has been set.
          example: "Premium outdoor gear and adventure accessories."
        State:
          type: string
          description: |-
            The current status of the advertiser account.

            | Value | Description |
            |---|---|
            | `ACTIVE` | Account is active and in good standing. |
            | `DELINQUENT` | Account has overdue payments or billing issues. |
          enum:
            - ACTIVE
            - DELINQUENT
          example: ACTIVE
        Website:
          type: string
          description: The advertiser's primary website URL.
          example: "www.nuttandco.com"
        AddressLine1:
          type: string
          description: First line of the advertiser's registered business address.
          example: "100 Commerce Drive"
        AddressLine2:
          type: string
          description: Second line of the address (suite, floor, unit, etc.). May be an empty string if not provided.
          example: "Suite 200"
        City:
          type: string
          description: City of the advertiser's registered business address.
          example: "Austin"
        CountryState:
          type: string
          description: State, province, or region associated with the advertiser's address. May return `OTHER` for non-standard jurisdictions, or an empty string if not provided.
          example: "TX"
        PostalCode:
          type: string
          description: ZIP or postal code of the advertiser's registered business address.
          example: "78701"
        Country:
          type: string
          description: Country of the advertiser's registered business address (e.g., `US`, `SOUTHAFRICA`).
          example: "US"
        IndirectTaxJurisdiction:
          type: string
          description: The tax jurisdiction used to calculate indirect taxes (e.g., GST, VAT) for this advertiser. May be an empty string if indirect taxes do not apply.
          example: ""
        VatRegistered:
          type: string
          description: Indicates whether the advertiser is registered for VAT. Returns `"true"` or `"false"` as a string value.
          enum:
            - "true"
            - "false"
          example: "false"
        OrganizationType:
          type: string
          description: |-
            The legal organization type of the advertiser.

            | Value | Description |
            |---|---|
            | `CORP` | Corporation or limited company. |
            | `NONP_GOV` | Non-profit organization or government entity. |
            | `OTHER` | Any other organization type. |
          enum:
            - CORP
            - NONP_GOV
            - OTHER
          example: CORP
        TaxId:
          type: string
          description: The advertiser's tax identification number. For security, only the last four digits are returned and the rest are masked (e.g., `XXXXX4832`). Returns an empty string if no tax ID has been provided.
          example: "XXXXX4832"
        IndirectTaxNumber:
          type: string
          description: The advertiser's indirect tax registration number (e.g., a GST, HST, or EU VAT number). Returns an empty string if not applicable.
          example: ""
        Timezone:
          type: string
          description: The advertiser's default timezone in IANA format. Used for scheduling and date-based reporting.
          example: "America/Chicago"
        Currency:
          type: string
          description: The advertiser's billing currency in ISO 4217 format.
          example: "USD"
        PhoneNumber:
          type: string
          description: The advertiser's primary contact phone number. Digits only — no spaces, dashes, or other formatting characters.
          example: "15125550191"
        DateCreated:
          type: string
          format: date-time
          description: The date and time when the advertiser account was created on impact.com, in ISO 8601 format with UTC offset.
          example: "2021-03-15T09:22:11-07:00"
        FinancialSetup:
          type: string
          description: |-
            How the advertiser is billed for impact.com platform fees.

            | Value | Description |
            |---|---|
            | `BILLED_BY_IR` | The advertiser is billed directly by impact.com. |
          enum:
            - BILLED_BY_IR
          example: BILLED_BY_IR
        AgencyOfRecord:
          type: string
          description: |-
            Indicates whether the authenticated agency is the designated **Agency of Record (AoR)** for this advertiser. An Agency of Record has full management authority over the advertiser's account. Returns `"true"` or `"false"` as a string value.
          enum:
            - "true"
            - "false"
          example: "true"
        RestAccountURL:
          type: string
          description: |-
            A pre-authenticated URL for making API calls directly to this advertiser's account. The URL embeds the advertiser's Account SID and Auth Token in the format `SID:AuthToken@api.impactradius.com/Advertisers/SID`, using the legacy `api.impactradius.com` domain.

            > **Security note:** Treat this value as a secret. It grants full API access to the advertiser's account. Never log it or expose it in client-side code.
          example: "IRxxxxxxxxxxxxxxxxx1:xxxxxxxxxxxxxxxxxxxxxxxx@api.impactradius.com/Advertisers/IRxxxxxxxxxxxxxxxxx1"
        Uri:
          type: string
          description: The relative URI for this advertiser resource within the Agency API. Append to `https://api.impact.com` to form the full resource URL.
          example: "/Agencies/IRq8mWJybvoQ1020978kbj7am8zzM2dBL1/Advertisers/1048291"
        AccountManager:
          type: string
          description: The full name of the impact.com account manager assigned to this advertiser. **Only present in the response when an account manager has been assigned** — the field will be absent if no manager is assigned.
          example: "Carrie Oakey"