africacompliancedata-com Countries API

openapi: 3.2.0
info:
  title: Africacompliancedata Com Countries API
  version: 1.0.0
  contact:
    name: Africa Compliance Data
    email: support@africacompliancedata.com
    url: https://africacompliancedata.com
  license:
    name: 'Proprietary: use under the Terms of Service'
    url: https://africacompliancedata.com/terms
  termsOfService: https://africacompliancedata.com/terms
  description: 'Operations tagged Countries across 2 of this provider''s published API definitions: africacompliancedata-com-openapi.json, africacompliancedata-com.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.africacompliancedata.com
security:
- ApiKey: []
- Bearer: []
tags:
- name: Countries
  description: 'Coverage, full country profiles, your account and your Pro country pack. All plans (tax sections of the profile: Compliance, and Pro for the countries of its pack).'
paths:
  /v1/account:
    get:
      tags:
      - Countries
      operationId: getAccount
      summary: 'Your key: plan, status, monthly quota, country pack, rate limit and today''s…'
      description: Daily allowances count distinct countries read per UTC day. Not counted against the monthly quota, and not a country read.
      responses:
        '200':
          description: Account
          content:
            application/json:
              schema:
                type: object
                properties:
                  plan:
                    type: string
                    enum:
                    - free
                    - developer
                    - pro
                    - compliance
                    - legacy_starter
                    - legacy_pro
                    - legacy_compliance
                    description: 'legacy_*: plans bought before 20 October 2026 (grandfathered)'
                  plan_name:
                    type: string
                  grandfathered:
                    type: boolean
                  key_ends_with:
                    type:
                    - string
                    - 'null'
                  expires_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  tax_data:
                    type: boolean
                  tax_data_countries:
                    type: string
                    enum:
                    - none
                    - country_pack
                    - all
                  holiday_watch:
                    type: boolean
                  webhooks:
                    type: string
                    enum:
                    - none
                    - holidays
                    - all
                  finance_law:
                    type: boolean
                  rate_limit_per_minute:
                    type:
                    - integer
                    - 'null'
                  status:
                    type: string
                    enum:
                    - active
                    description: A paused key gets 403 Access paused instead
                  monthly_quota:
                    type: object
                    properties:
                      month:
                        type: string
                        description: YYYY-MM (UTC)
                      limit:
                        type:
                        - integer
                        - 'null'
                        description: 'null: no monthly quota (grandfathered plans)'
                      used:
                        type: integer
                      remaining:
                        type:
                        - integer
                        - 'null'
                      resets_at:
                        type: string
                        format: date-time
                  country_pack:
                    $ref: '#/components/schemas/CountryPack'
                  countries_today:
                    type: object
                    additionalProperties:
                      type: integer
                  daily_allowance:
                    type: object
                    additionalProperties:
                      type: integer
                  tax_data_countries_7_days:
                    type: object
                    properties:
                      used:
                        type: integer
                      allowance:
                        type: integer
                  manage_billing_and_keys:
                    type: string
                  dataset_version:
                    type: string
                  data_revision:
                    $ref: '#/components/schemas/DataRevision'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Unavailable'
        '403':
          $ref: '#/components/responses/Paused'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://api.africacompliancedata.com
  /v1/account/countries:
    get:
      tags:
      - Countries
      operationId: getCountryPack
      summary: 'Your Pro country pack: the countries of tax data, and when it can next be…'
      description: Not counted against the monthly quota. The first countries a Pro key requests tax data for join the pack while it has room.
      responses:
        '200':
          description: Country pack
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountryPack'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 'Not a Pro key (Compliance and grandfathered Pro: every country; Free and Developer: no tax data)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
    post:
      tags:
      - Countries
      operationId: setCountryPack
      summary: Set your Pro country pack. Pro plan
      description: Adding countries to free places is always possible. A change that removes a country (a swap) is possible once every 30 days (409 with next_swap_from and Retry-After otherwise). Not counted against the monthly quota.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - countries
              properties:
                countries:
                  type: array
                  maxItems: 54
                  items:
                    type: string
                  description: ISO codes, at most the pack's size (5 + extra countries)
            example:
              countries:
              - KE
              - NG
              - GH
              - ZA
              - EG
      responses:
        '200':
          description: The pack after the change
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CountryPack'
                - type: object
                  properties:
                    swapped:
                      type: boolean
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Not a Pro key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: A swap within 30 days of the last one; the pack is unchanged
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Error'
                - $ref: '#/components/schemas/CountryPack'
        '413':
          description: Request body over 2 KB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Not a JSON body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
    servers:
    - url: https://api.africacompliancedata.com
  /v1/countries:
    get:
      tags:
      - Countries
      operationId: listCountries
      summary: List the 54 countries with currency and coverage per feature
      description: On Free and Developer, coverage lists only the holiday features.
      responses:
        '200':
          description: Countries
          content:
            application/json:
              schema:
                type: object
                properties:
                  countries:
                    type: array
                    items:
                      $ref: '#/components/schemas/CountrySummary'
                  years:
                    type: array
                    items:
                      type: integer
                    description: First and last year covered
                  dataset_version:
                    type: string
                  data_revision:
                    $ref: '#/components/schemas/DataRevision'
                  disclaimer:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Unavailable'
        '403':
          $ref: '#/components/responses/Paused'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://api.africacompliancedata.com
  /v1/countries/{country}:
    get:
      tags:
      - Countries
      operationId: getCountryProfile
      summary: Full compliance profile of one country
      description: Shares the per-key limit of 5 requests per minute with the holiday watch. Tax sections need the Compliance plan, or the Pro plan for a country of its pack (otherwise they are listed in not_in_plan; a profile never adds a country to the pack). VAT history, treaties and finance-law digests have their own endpoints.
      parameters:
      - $ref: '#/components/parameters/Country'
      responses:
        '200':
          description: Profile
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  iso2:
                    type: string
                  name:
                    type: string
                  currency:
                    type: string
                  coverage:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Coverage'
                  sources:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Source'
                  not_in_plan:
                    type: array
                    items:
                      type: string
                  upgrade:
                    type: string
                  dataset_version:
                    type: string
                  data_revision:
                    $ref: '#/components/schemas/DataRevision'
                  disclaimer:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Unavailable'
        '403':
          $ref: '#/components/responses/Paused'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/BulkLimited'
    servers:
    - url: https://api.africacompliancedata.com
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    Coverage:
      type: string
      enum:
      - ready
      - partial
      - gap
    CountrySummary:
      type: object
      properties:
        iso2:
          type: string
        name:
          type: string
        currency:
          type: string
        coverage:
          type: object
          description: 'Per feature: holidays, holiday_announcements, vat, wht, tin_format, filing_deadlines, vat_history, treaties, finance_law, payroll_tax, social_security (Free and Developer: holiday features only)'
          additionalProperties:
            $ref: '#/components/schemas/Coverage'
    DataRevision:
      type: string
      description: 'Short commit id of the data the answer was built from (e.g. 928cb72b). dataset_version is the build date: the daily rebuild changes it with no data change, while data_revision changes only when the data does. Keep it with saved results to know exactly which data you used.'
      example: 928cb72b
    CountryPack:
      type: object
      description: 'Pro plan: the countries of tax data'
      properties:
        countries:
          type: array
          items:
            type: string
          description: Active pack countries, in the order they joined
        inactive:
          type: array
          items:
            type: string
          description: 'Countries beyond the pack''s size after an add-on ended: refused until there is room'
        size:
          type: integer
          description: base + extra
        base:
          type: integer
          const: 5
        extra:
          type: integer
          description: Extra countries bought as add-ons
        last_swap:
          type:
          - string
          - 'null'
          format: date-time
        next_swap_from:
          type:
          - string
          - 'null'
          format: date-time
          description: 'When a change that removes a country is possible again (null: now)'
    Source:
      type: object
      properties:
        url:
          type:
          - string
          - 'null'
          description: null when the official text is not available online; 'note' then explains it
        note:
          type: string
          description: Present when url is null
        legal_basis:
          type: string
        source_type:
          type: string
          description: e.g. statute, gazette, revenue_authority; 'secondary' when no official text has been confirmed
        effective_date:
          type:
          - string
          - 'null'
        confidence:
          type: string
          enum:
          - high
          - medium
          - low
        last_verified:
          type: string
          format: date
  responses:
    Paused:
      description: Key paused for review after unusual bulk access ('Access paused')
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Missing or invalid parameter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unavailable:
      description: Key check temporarily unavailable, or webhook storage unavailable (webhook endpoints); retry after Retry-After seconds
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Unknown country, path or webhook id
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: 'Monthly quota reached (until 00:00 UTC on the 1st; X-Quota-Limit and X-Quota-Remaining: 0), rate limit for the plan exceeded, or key checks busy (many new keys from your network); see Retry-After'
      headers:
        Retry-After:
          schema:
            type: integer
        X-Quota-Limit:
          schema:
            type: integer
        X-Quota-Remaining:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BulkLimited:
      description: Monthly quota reached, plan rate limit exceeded, or the shared limit of 5 requests per minute for full country profiles and the holiday watch, or key checks busy (many new keys from your network); see Retry-After
      headers:
        Retry-After:
          schema:
            type: integer
        X-Quota-Limit:
          schema:
            type: integer
        X-Quota-Remaining:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    Country:
      name: country
      in: path
      required: true
      description: ISO 3166-1 alpha-2 code, e.g. KE, NG, ZA.
      schema:
        type: string
        pattern: ^[A-Za-z]{2}$
      example: KE
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
    Bearer:
      type: http
      scheme: bearer
      description: The same API key as a bearer token.
x-refined-from:
- africacompliancedata-com-openapi.json
- africacompliancedata-com.json