Dow Jones List Import API

openapi: 3.2.0
info:
  title: Advanced Screening and Monitoring List Import API
  description: 'Dow Jones


    ### Rate limits


    Most endpoints are subject to a general rate limit of 10,000 requests per user per 15 minutes.


    Some endpoints are also subject to a global concurrent request limit of 5 simultaneous requests per customer.'
  version: '3'
  license: {}
  contact: {}
servers:
- url: API_INSTANCE
security:
- basicAuth: []
- jwt: []
- clientCert: []
tags:
- name: List Import
  description: The List API allows clients to bulk load internal list entities into the Screening system.
paths:
  /list/import:
    post:
      summary: Create a new or update a current list entity
      description: "The List entity API allows identities to be screened against entities that appear on lists, for example, watchlists including sanctioned entities or PEP's.\nThis API endpoint is used to add or change list entities.\n### Rate Limits\n\nThis endpoint is subject to a general rate limit of 10,000 requests per user per 15 minutes, and a global concurrent request limit of 5 simultaneous requests per customer.\n\n<!-- operational-characteristics:start -->\n\n### Operational characteristics\n\nValues below are measured from production traffic. Only collected values are shown.\n\n**Latency distribution**\n\nLatency values are shown as milliseconds below 1 s, seconds with one decimal place below 1 min, otherwise as M:SS (min).\n\n| Metric | Value |\n| --- | --- |\n| Median | 2.4 s |\n| 90th percentile | 2.5 s |\n| 95th percentile | 2.6 s |\n| 98th percentile | 2.6 s |\n| 99th percentile | 2.6 s |\n<!-- operational-characteristics:end -->\n\n## Checking the list processing progress\n\nList entities are queued using Apache kafka. Checking the lag of the digest-torch-list group on the list-digest topic shows how many messages there are still to process. This can be done using the following command:\n`$ …/apps/torch_tools/bin/kafka/describeGroup.sh torch-list-digest``\n\nLists are only fully processed once the second stage of processing is also complete. The second stage of processing can be checked using a similar command:\n`$ …/apps/torch_tools/bin/kafka/describeGroup.sh torch-list-deltas``\n\nWhen the lag is zero for both topics, list processing is fully complete.\n\n## Checking log files\n\nA pm2 log file is produced for each of the two stages of processing.\n•\tpm2 logs digest_torch_lists\n•\tpm2 logs digest_torch_list_deltas\nFor more detailed information, you can check the sensitive log files:\n\n```\n$ tail -f digest_torch_lists-sensitive.log\n$ tail -f /data0/logs/node/digest_torch_list_deltas-sensitive.log\n```\n"
      operationId: listImport
      tags:
      - List Import
      x-operational-characteristics:
        description: 'Operational characteristics from production log analysis (generatedAt: 2026-06-16T10:56:29.271Z).

          '
        latencyDistribution:
          median: 2355.08
          p90: 2474.53
          p95: 2600.04
          p98: 2600.04
          p99: 2600.04
          sampleSize: 2194
      parameters:
      - name: source
        in: query
        required: true
        schema:
          type: string
        description: The source is the name of the collection of list entities within the provider. This string is shown in the user interface, and should be URL encoded, for example “My Test List” would be encoded as “My%20Test%20List”.
      - name: provider
        in: query
        required: true
        schema:
          type: string
        description: The provider URL query parameter identifies who created the list entities, for example dowjones. This should be a single word without special characters.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              allOf:
              - description: The list entity associated with this evidence. Present if the evidence is of type 'list' and the 'lists' enrichment is enabled
                oneOf:
                - type: object
                  allOf:
                  - type: object
                    required:
                    - profileID
                    - name
                    - activeStatus
                    properties:
                      profileID:
                        type: string
                        description: Unique ID for this profile, used when creating relationships
                      entityType:
                        type: string
                        enum:
                        - listPerson
                        - listAircraft
                        - listLocation
                        - listOrganisation
                        - listVessel
                      name:
                        type: string
                      activeStatus:
                        type: string
                        enum:
                        - Active
                        - Inactive
                        description: Defines whether the entity profile is active or inactive. Typically, entities that are active have anb active membership of at least one active list.
                      identityNumbers:
                        description: Identity numbers associated with the entity, for example Company Identification Number. Each array item consists of a type string that lables the ID number or code and a value string.
                        type: array
                        items:
                          type: object
                          required:
                          - type
                          - value
                          properties:
                            type:
                              type: string
                            value:
                              type: string
                            notes:
                              type: string
                      addresses:
                        type: array
                        items:
                          type: object
                          properties:
                            line1:
                              type: string
                            line2:
                              type: string
                            line3:
                              type: string
                            line4:
                              type: string
                            poBox:
                              type: string
                            city:
                              type: string
                            state:
                              type: string
                            province:
                              type: string
                            country:
                              type: string
                            countryCode:
                              type: string
                              maxLength: 2
                              minLength: 2
                              description: 'An ISO-3166 alpha-2 country code digraph as defined here: <https://www.iso.org/iso-3166-country-codes.html>

                                '
                              enum:
                              - AD
                              - AE
                              - AF
                              - AG
                              - AI
                              - AL
                              - AM
                              - AO
                              - AQ
                              - AR
                              - AS
                              - AT
                              - AU
                              - AW
                              - AX
                              - AZ
                              - BA
                              - BB
                              - BD
                              - BE
                              - BF
                              - BG
                              - BH
                              - BI
                              - BJ
                              - BL
                              - BM
                              - BN
                              - BO
                              - BQ
                              - BR
                              - BS
                              - BT
                              - BV
                              - BW
                              - BY
                              - BZ
                              - CA
                              - CC
                              - CD
                              - CF
                              - CG
                              - CH
                              - CI
                              - CK
                              - CL
                              - CM
                              - CN
                              - CO
                              - CR
                              - CU
                              - CV
                              - CW
                              - CX
                              - CY
                              - CZ
                              - DE
                              - DJ
                              - DK
                              - DM
                              - DO
                              - DZ
                              - EC
                              - EE
                              - EG
                              - EH
                              - ER
                              - ES
                              - ET
                              - FI
                              - FJ
                              - FK
                              - FM
                              - FO
                              - FR
                              - GA
                              - GB
                              - GD
                              - GE
                              - GF
                              - GG
                              - GH
                              - GI
                              - GL
                              - GM
                              - GN
                              - GP
                              - GQ
                              - GR
                              - GS
                              - GT
                              - GU
                              - GW
                              - GY
                              - HK
                              - HM
                              - HN
                              - HR
                              - HT
                              - HU
                              - ID
                              - IE
                              - IL
                              - IM
                              - IN
                              - IO
                              - IQ
                              - IR
                              - IS
                              - IT
                              - JE
                              - JM
                              - JO
                              - JP
                              - KE
                              - KG
                              - KH
                              - KI
                              - KM
                              - KN
                              - KP
                              - KR
                              - KW
                              - KY
                              - KZ
                              - LA
                              - LB
                              - LC
                              - LI
                              - LK
                              - LR
                              - LS
                              - LT
                              - LU
                              - LV
                              - LY
                              - MA
                              - MC
                              - MD
                              - ME
                              - MF
                              - MG
                              - MH
                              - MK
                              - ML
                              - MM
                              - MN
                              - MO
                              - MP
                              - MQ
                              - MR
                              - MS
                              - MT
                              - MU
                              - MV
                              - MW
                              - MX
                              - MY
                              - MZ
                              - NA
                              - NC
                              - NE
                              - NF
                              - NG
                              - NI
                              - NL
                              - 'NO'
                              - NP
                              - NR
                              - NU
                              - NZ
                              - OM
                              - PA
                              - PE
                              - PF
                              - PG
                              - PH
                              - PK
                              - PL
                              - PM
                              - PN
                              - PR
                              - PS
                              - PT
                              - PW
                              - PY
                              - QA
                              - RE
                              - RO
                              - RS
                              - RU
                              - RW
                              - SA
                              - SB
                              - SC
                              - SD
                              - SE
                              - SG
                              - SH
                              - SI
                              - SJ
                              - SK
                              - SL
                              - SM
                              - SN
                              - SO
                              - SR
                              - SS
                              - ST
                              - SV
                              - SX
                              - SY
                              - SZ
                              - TC
                              - TD
                              - TF
                              - TG
                              - TH
                              - TJ
                              - TK
                              - TL
                              - TM
                              - TN
                              - TO
                              - TR
                              - TT
                              - TV
                              - TW
                              - TZ
                              - UA
                              - UG
                              - UM
                              - US
                              - UY
                              - UZ
                              - VA
                              - VC
                              - VE
                              - VG
                              - VI
                              - VN
                              - VU
                              - WF
                              - WS
                              - XK
                              - YE
                              - YT
                              - ZA
                              - ZM
                              - ZW
                            postcode:
                              type: string
                            addressType:
                              type: string
                      enhancedRiskCountryCode:
                        type: string
                        maxLength: 2
                        minLength: 2
                        description: 'An ISO-3166 alpha-2 country code digraph as defined here: <https://www.iso.org/iso-3166-country-codes.html>

                          '
                        enum:
                        - AD
                        - AE
                        - AF
                        - AG
                        - AI
                        - AL
                        - AM
                        - AO
                        - AQ
                        - AR
                        - AS
                        - AT
                        - AU
                        - AW
                        - AX
                        - AZ
                        - BA
                        - BB
                        - BD
                        - BE
                        - BF
                        - BG
                        - BH
                        - BI
                        - BJ
                        - BL
                        - BM
                        - BN
                        - BO
                        - BQ
                        - BR
                        - BS
                        - BT
                        - BV
                        - BW
                        - BY
                        - BZ
                        - CA
                        - CC
                        - CD
                        - CF
                        - CG
                        - CH
                        - CI
                        - CK
                        - CL
                        - CM
                        - CN
                        - CO
                        - CR
                        - CU
                        - CV
                        - CW
                        - CX
                        - CY
                        - CZ
                        - DE
                        - DJ
                        - DK
                        - DM
                        - DO
                        - DZ
                        - EC
                        - EE
                        - EG
                        - EH
                        - ER
                        - ES
                        - ET
                        - FI
                        - FJ
                        - FK
                        - FM
                        - FO
                        - FR
                        - GA
                        - GB
                        - GD
                        - GE
                        - GF
                        - GG
                        - GH
                        - GI
                        - GL
                        - GM
                        - GN
                        - GP
                        - GQ
                        - GR
                        - GS
                        - GT
                        - GU
                        - GW
                        - GY
                        - HK
                        - HM
                        - HN
                        - HR
                        - HT
                        - HU
                        - ID
                        - IE
                        - IL
                        - IM
                        - IN
                        - IO
                        - IQ
                        - IR
                        - IS
                        - IT
                        - JE
                        - JM
                        - JO
                        - JP
                        - KE
                        - KG
                        - KH
                        - KI
                        - KM
                        - KN
                        - KP
                        - KR
                        - KW
                        - KY
                        - KZ
                        - LA
                        - LB
                        - LC
                        - LI
                        - LK
                        - LR
                        - LS
                        - LT
                        - LU
                        - LV
                        - LY
                        - MA
                        - MC
                        - MD
                        - ME
                        - MF
                        - MG
                        - MH
                        - MK
                        - ML
                        - MM
                        - MN
                        - MO
                        - MP
                        - MQ
                        - MR
                        - MS
                        - MT
                        - MU
                        - MV
                        - MW
                        - MX
                        - MY
                        - MZ
                        - NA
                        - NC
                        - NE
                        - NF
                        - NG
                        - NI
                        - NL
                        - 'NO'
                        - NP
                        - NR
                        - NU
                        - NZ
                        - OM
                        - PA
                        - PE
                        - PF
                        - PG
                        - PH
                        - PK
                        - PL
                        - PM
                        - PN
                        - PR
                        - PS
                        - PT
                        - PW
                        - PY
                        - QA
                        - RE
                        - RO
                        - RS
                        - RU
                        - RW
                        - SA
                        - SB
                        - SC
                        - SD
                        - SE
                        - SG
                        - SH
                        - SI
                        - SJ
                        - SK
                        - SL
                        - SM
                        - SN
                        - SO
                        - SR
                        - SS
                        - ST
                        - SV
                        - SX
                        - SY
                        - SZ
                        - TC
                        - TD
                        - TF
                        - TG
                        - TH
                        - TJ
                        - TK
                        - TL
                        - TM
                        - TN
                        - TO
                        - TR
                        - TT
                        - TV
                        - TW
                        - TZ
                        - UA
                        - UG
                        - UM
                        - US
                        - UY
                        - UZ
                        - VA
                        - VC
                        - VE
                        - VG
                        - VI
                        - VN
                        - VU
                        - WF
                        - WS
                        - XK
                        - YE
                        - YT
                        - ZA
                        - ZM
                        - ZW
                      profileNotes:
                        type: string
                      lists:
                        type: array
                        items:
                          type: object
                          description: "Each entity is on one or more lists. Lists are defined as part of a hierarchy, and may have one or more levels of parent list. \nFor example, a Special Interest Person (SIP) list may have sub-lists for different crime regions and beneath those for different kinds of crime.\n"
                          properties:
                            id:
                              type: string
                              description: ID of the list that the entity is on
                            name:
                              type: string
                              description: Name of the list that the entity is on
                            hierarchy:
                              type: array
                              description: "Contains an entry for the list itself (that the entity is on) and each of its parents. \nThe list that the entity is on will be the lowest element in the hierarchy. \nEach lists parent element contains the ID of the list above it. \nThat list should also be included in this hierarchy definition. The top level list has no parent.\n"
                              items:
                                id:
                                  type: string
                                name:
                                  type: string
                                parent:
                                  type: string
                            active:
                              type: boolean
                              description: "Defines whether the entity is currently a member of this list. If an entity was previously a member of the list and has since been removed, this property would be set to false. \nTypically, when this value is set to false the to property would be populated to indicate when the entity was removed from the list.\n"
                            listActive:
                              type: boolean
                              description: 'Defines whether the list itself is currently active. For example, a list relating to a sanctions regime which has been decommissioned would have listActive set to false.

                                '
                            additionalFields:
                              type: array
                              description: 'Any additional properties of the list as key/value pairs

                                '
                              items:
                                key:
                                  type: string
                                value:
                                  type: string
                            since:
                              type: string
                              format: date
                              description: When the entity was added to the list
                              example: '2023-12-25'
                            to:
                              type: string
                              format: date
                              description: If the entity is no longer on this list (i.e. active is false), this property can be provided to show when the entity was removed from the list
                              example: '2023-12-25'
                      sources:
                        description: Sources used when compiling the list entity
                        type: array
                        items:
                          type: string
                      aliases:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                            entityName:
                              type: string
                            suffix:
                              type: string
                            forename:
                              type: string
                            middlename:
                              type: string
                            surname:
                              type: string
                            maidenName:
                              type: string
                            singleStringName:
                              type: string
                            titleHonorific:
                              type: string
                      relationships:
                        type: array
                        description: Relationships between this entity and the other list entities. Properties on a relationship are; current - boolean, is this a current relationship?, type - string, the type of relationship, profileID - the profile ID of the entity
                        items:
                          type: object
                          properties:
                            current:
                              type: boolean
                            type:
                              type: string
                            profileID:
                              type: integer
                      categories:
                        type: array
                        description: Categories are optional but can be used to capture arbitrary categories for an entity. Categories have a type, reflecting the type of category, for example 'risk'
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              description: The type of risk category
                            value:
                              type: string
                              description: Value of the risk e.g. high
                      hash:
                        type: string
                        description: A hash of the entity record can optionally be provided. The hash is generated by the client and can be used to reconsile the version of the entity stored in the system with versions mastered in the source system.
                  properties:
                    person:
                      type: object
                      description: 'The person entity schema must contain the following fileds; firstName, middleName, surname, name

                        '
                      properties:
                        name:
                          type: string
                          description: Full name of the person. Can be used as well as, or instead of, fields for individual name parts
                        firstName:
                          type: string
                          description: Given name of the person
                        surname:
                          type: string
                          description: Family name of the person
                        aliases:
                          type: array
                          description: An aray of alternative names by which a person is known. Fields in each name are as for the main name fields with some additions
                          items:
                            type: object
                            properties:
                              type:
                                type: string
                              firstName:
                                type: string
                              surname:
                                type: string
                              middleName:
                                type: string
                              titleHonorific:
                                type: string
                              maidenName:
                                type: string
                        gender:
                          type: string
                          enum:
                          - MALE
                          - FEMALE
                          - OTHER
                          description: Known gender type of the person, must be in capitals
                        deceased:
                          type: boolean
                          description: Is the person deceased?
                        birthPlace:
                          type: string
                          description: The name of the persons birthplace. Populated automatically from birthPlaceCountryCode
                        birthPlaceCity:
                          type: string
                          description: The persons city of birth
                        dateOfBirthArray:
                          type: array
                          description: Possible values for the persons date of birth. This is an array to allow for the uncertanty in reported dates
                          items:
                            type: string
                            format: date
                      

# --- truncated at 32 KB (280 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dow-jones/refs/heads/main/openapi/dow-jones-list-import-api-openapi.yml