africacompliancedata-com Private mode API

openapi: 3.2.0
info:
  title: Africacompliancedata Com Private mode 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 Private mode 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: Private mode
  description: Signed country-year bundles for computing on your own machine (the SDKs' private mode). Holiday parts on all plans; tax parts on Pro (countries of its pack) and Compliance.
paths:
  /v1/countries/{country}/bundle:
    get:
      tags:
      - Private mode
      operationId: getCountryBundle
      summary: Signed country-year bundle, to compute holidays, business days, VAT on a date…
      description: 'What the SDKs'' private mode needs for one country and year: the year''s holidays with their status (rule, confirmed, estimated, observed, bridge) in every scope, the weekend, coverage, the sources with their confidence, and the disclaimer; with the tax parts, also the VAT rates, the dated VAT history, the filing-deadline rules and the payroll data (PAYE bands and contributions in dated periods, with the currency). The client computes the answers itself, so the dates, ranges, months and day counts of its queries are not sent: the only details of its queries in the request are the country and the year. Plans: Free and Developer get the holiday parts; Compliance gets everything; Pro gets the tax parts for the countries of its pack. On Pro, parts=all uses the pack as a tax endpoint does: a country joins a pack that has room; with a full pack that does not hold it, the answer has the holiday parts and bundle.not_included.tax gives the reason. parts=holidays never changes the pack. Signed with Ed25519 (the same key as GET /v1/tax-id/rules) over the canonical JSON of ''bundle'' (object keys sorted, no whitespace, strings as JSON.stringify writes them, integers and plain decimals such as 7.5 only). The top-level ''disclaimer'' is the key''s own copy, outside the signature; it equals bundle.disclaimer apart from invisible characters. Do not use a bundle past bundle.expires_at: 1 day after issued_at for the current and later years (holiday statuses change when an estimated date is confirmed), 30 days for past years. Counts as one request against the monthly quota and as a read of that country. Cache-Control: private.'
      parameters:
      - $ref: '#/components/parameters/Country'
      - name: year
        in: query
        required: true
        schema:
          type: integer
          minimum: 2025
          maximum: 2030
      - name: parts
        in: query
        required: false
        description: 'all (default): the parts the plan includes for this country; holidays: the holiday parts only (never changes a Pro pack)'
        schema:
          type: string
          enum:
          - all
          - holidays
          default: all
      responses:
        '200':
          description: Signed bundle
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountryBundle'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Paused'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: Signed bundles not available on this server yet (or the key check is temporarily unavailable)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.africacompliancedata.com
components:
  schemas:
    Coverage:
      type: string
      enum:
      - ready
      - partial
      - gap
    VatPeriod:
      type: object
      properties:
        rate:
          type: number
        from:
          type:
          - string
          - 'null'
          format: date
        to:
          type:
          - string
          - 'null'
          format: date
        from_note:
          type: string
          description: When the period started before the documented history, e.g. 'in force on 2015-01-01 (earlier start not covered)'
        legal_basis:
          type: string
        source_url:
          type:
          - string
          - 'null'
        confidence:
          type: string
          enum:
          - high
          - medium
          - low
        notes:
          type: string
    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
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    Holiday:
      type: object
      properties:
        date:
          type: string
          format: date
        name:
          type: string
        rule_id:
          type:
          - string
          - 'null'
          description: Absent for ad-hoc days off
        status:
          type: string
          enum:
          - rule
          - confirmed
          - estimated
          - observed
          - bridge
        scope:
          type: string
          description: national, or the group a holiday is limited to
        observed_for:
          type: string
          format: date
          description: 'For a substitute day: the date of the holiday it replaces'
        moved_from:
          type: string
          format: date
          description: Original date of a holiday officially moved
        bridge_for:
          type: string
          format: date
          description: 'For a bridge day: the holiday it bridges to'
        estimated:
          type: boolean
          description: 'true on a weekend substitute of an estimated (moon-sighted) date: it moves with the announced date'
        source_url:
          type:
          - string
          - 'null'
          description: Official announcement (confirmed dates); null when the official text is not online (source_note says where it was published)
        source_note:
          type: string
          description: Where the announcement was made when it is not published online, or that the date is known from a press report of the official announcement
    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
    CountryBundle:
      type: object
      required:
      - bundle
      - signature
      - disclaimer
      properties:
        bundle:
          type: object
          description: The signed payload
          required:
          - format
          - kind
          - country
          - year
          - years
          - parts
          - dataset_version
          - issued_at
          - expires_at
          - key_id
          - disclaimer
          - country_data
          - calendar
          properties:
            format:
              type: integer
              enum:
              - 1
            kind:
              type: string
              enum:
              - country_year
            country:
              type: string
            year:
              type: integer
            years:
              type: array
              items:
                type: integer
              description: First and last year the dataset covers
            parts:
              type: array
              items:
                type: string
                enum:
                - holidays
                - tax
            dataset_version:
              type: string
            data_revision:
              $ref: '#/components/schemas/DataRevision'
            issued_at:
              type: string
              format: date-time
            expires_at:
              type: string
              format: date-time
              description: '1 day after issued_at for the current and later years, 30 days for past years: do not use the bundle after this'
            key_id:
              type: string
              description: First 16 hex digits of the SHA-256 of the signing public key
            disclaimer:
              type: string
            country_data:
              type: object
              description: 'The country''s fields as the API uses them: iso2, name, weekend (ISO weekday numbers, 1 = Monday), coverage, holidays (source_ref, weekend_rule, notes), holiday_announcements, calendar_incomplete_years, calendar_any (whether any year has a holiday), sources (with confidence); with the tax parts also vat, vat_history, deadlines, currency and payroll (payroll_tax and contributions periods, as in /payroll-tax and /social-security)'
              properties:
                weekend:
                  type: array
                  items:
                    type: integer
                coverage:
                  type: object
                  additionalProperties:
                    $ref: '#/components/schemas/Coverage'
                sources:
                  type: object
                  additionalProperties:
                    $ref: '#/components/schemas/Source'
                vat_history:
                  type: object
                  properties:
                    covered_from:
                      type:
                      - string
                      - 'null'
                    periods:
                      type: array
                      items:
                        $ref: '#/components/schemas/VatPeriod'
            calendar:
              type: object
              description: The year's holidays (every scope), keyed by the year
              additionalProperties:
                type: array
                items:
                  $ref: '#/components/schemas/Holiday'
            not_included:
              type: object
              properties:
                tax:
                  type: string
                  description: Why the tax parts are not included (the plan, or a full Pro pack)
        signature:
          type: object
          properties:
            alg:
              type: string
              enum:
              - Ed25519
            key_id:
              type: string
            value:
              type: string
              description: Base64 Ed25519 signature of the UTF-8 canonical JSON of 'bundle'
        disclaimer:
          type: string
          description: The disclaimer as in every answer for this key (outside the signature)
  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'
    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'
  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