Dow Jones Client Import API

openapi: 3.2.0
info:
  title: Advanced Screening and Monitoring Client 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: Client Import
  description: The Client Import API allows clients to bulk load client records representing entities to be screened as part of continuous monitoring.
paths:
  /client/import:
    get:
      operationId: clientImportList
      summary: List all import jobs
      description: 'This endpoint lists all client import jobs

        ### Rate Limits


        This endpoint is subject to a general rate limit of 10,000 requests per user per 15 minutes.

        '
      tags:
      - Client Import
      responses:
        '200':
          description: A response containing information about all submitted client import jobs
          content:
            application/json:
              schema:
                description: The status of all client import jobs
                type: array
                items:
                  type: object
                  description: The status of a client import job.
                  properties:
                    id:
                      type: integer
                      description: Unique identifier for the job
                    timeCreated:
                      type: integer
                      description: Unix timestamp for when the content was created
                    timeStaged:
                      type: integer
                      description: Unix timestamp for when the content was staged
                    state:
                      type: string
                      description: State of the job
                      enum:
                      - STAGING
                      - STAGED
                      - IMPORTED
                      - COMPLETE
                      - ERRORED
                    itemsFailed:
                      type: integer
                      description: Number of items that failed
                    itemsUploaded:
                      type: integer
                      description: Number of items that were uploaded
                    relationshipsUploaded:
                      type: integer
                      description: Number of relationships that were uploaded
                    itemsStaged:
                      type: integer
                      description: Number of items that were staged
                    itemsFailedStaging:
                      type: integer
                      description: Number of items that failed staging
                    relationshipsAdded:
                      type: integer
                      description: Number of relationships that were added
                    relationshipsFailed:
                      type: integer
                      description: Number of relationships that failed
                    itemsImported:
                      type: integer
                      description: Number of items that were imported
                    itemsFailedImporting:
                      type: integer
                      description: Number of items that failed importing
                    itemsForAssessment:
                      type: integer
                      description: Number of items for assessment
                    itemsAssessed:
                      type: integer
                      description: Number of items assessed
                    itemsFailedAssessment:
                      type: integer
                      description: Number of items that failed assessment
                    name:
                      type: string
                      description: Name of the job
                    removeInvalidRelationships:
                      type: boolean
                      description: Whether to remove invalid relationships
                    validate:
                      type: boolean
                      description: Whether to validate
                    clientKey:
                      type: string
                      description: Client key for multi-tenant systems
                    lastUpdated:
                      type: integer
                      description: Unix timestamp for when the job was last updated
                    validationWarnings:
                      type: integer
                      description: Number of validation warnings
              example:
              - id: 52
                timeCreated: 1692273794423
                timeStaged: 1692273794726
                state: COMPLETE
                itemsFailed: 1
                itemsUploaded: 1
                relationshipsUploaded: 0
                itemsStaged: 0
                itemsFailedStaging: 1
                relationshipsAdded: 0
                relationshipsFailed: 0
                itemsImported: 0
                itemsFailedImporting: 0
                itemsForAssessment: 0
                itemsAssessed: 0
                itemsFailedAssessment: 0
                name: Bulk Client Job
                removeInvalidRelationships: true
                validate: true
                clientKey: lowercasekey
                lastUpdated: 1692273796030
                validationWarnings: 0
              - id: 86
                timeCreated: 1692296462489
                timeStaged: 1692296462919
                state: COMPLETE
                itemsFailed: 0
                itemsUploaded: 40
                relationshipsUploaded: 0
                itemsStaged: 40
                itemsFailedStaging: 0
                relationshipsAdded: 0
                relationshipsFailed: 0
                itemsImported: 40
                itemsFailedImporting: 0
                itemsForAssessment: 40
                itemsAssessed: 40
                itemsFailedAssessment: 0
                name: Example
                removeInvalidRelationships: true
                validate: true
                clientKey: lowercasekey
                lastUpdated: 1692296470953
                validationWarnings: 0
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (e.g. the user does not have the correct permission)
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    description: Error code that can be used when contacting support or looking up information
                  message:
                    type: string
                    description: Human-readable description of the error, which will usually indicate possible next steps if applicable
                  status:
                    type: number
                    description: HTTP Error code
    post:
      summary: Bulk import client records
      description: 'Labyrinth Screening supports ongoing monitoring of entities (referred to as "clients") against risks. The Client Import API supports the loading and updating of clients that should be monitored.

        ### Rate Limits


        This 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.


        <!-- operational-characteristics:start -->


        ### Operational characteristics


        Values below are measured from production traffic. Only collected values are shown.


        **Latency distribution**


        Latency values are shown as milliseconds below 1 s, seconds with one decimal place below 1 min, otherwise as M:SS (min).


        | Metric | Value |

        | --- | --- |

        | Median | 127 ms |

        | 90th percentile | 208 ms |

        | 95th percentile | 267 ms |

        | 98th percentile | 310 ms |

        | 99th percentile | 377 ms |

        <!-- operational-characteristics:end -->


        The client import process is asynchronous. Clients are loaded in batches, referred to as "jobs". Once loaded, the job goes through several stages of processing until all the clients are loaded.


        The API provides access to the status of any submitted client import job, including any errors that have occurred during processing. (see the endpoints `/client/import/{job_id}/status` and `/client/import/{job_id}/errors`)


        Client records can be submitted as line-delimited JSON (`application/octet-stream`) or as an Excel macro-enabled workbook (`.xlsm`, `application/vnd.ms-excel.sheet.macroenabled.12`).

        '
      operationId: clientBulkImport
      tags:
      - Client Import
      x-operational-characteristics:
        description: 'Operational characteristics from production log analysis (generatedAt: 2026-06-16T10:56:29.271Z).

          '
        latencyDistribution:
          median: 126.33
          p90: 207.8
          p95: 266.37
          p98: 309.14
          p99: 376.98
          sampleSize: 4184238
      parameters:
      - name: removeInvalidRelationships
        in: query
        required: false
        schema:
          type: boolean
          default: true
        description: 'This flag controls how the system handles cases where a client that is referenced in a relationship is not found in the client import job and is not already loaded.


          If the flag is set to `true`, the relationship will be ignored and not loaded. If the flag is set to `false`, the relationship will be loaded, allowing the missing referenced client to be loaded as part of a subsequence client load job.

          '
      - name: batch
        in: query
        required: false
        schema:
          type: boolean
          default: true
        description: 'Indicates that the clients in this client import job should be handled as a single batch and immediately loaded together.


          If this value is set to `false`, the system will not load the clients in this job immediately and will instead wait until there are more clients to load in requests where this parameter is set to `false`, or until a certain amount of time has passed. This allows the system to batch smaller client load jobs internally and process them as part of a larger internal batch, which is more efficiently.


          IMPORTANT: Loading large numbers of smaller client load jobs without this value set to `false` is not recommended as it can lead to overheads that can impact system performance.

          '
      requestBody:
        required: true
        description: 'The set of client records to be imported in a new bulk client import job.


          Submit as line-delimited JSON (`application/octet-stream`), where each line contains a complete JSON record that adheres to the client import schema, or as an Excel macro-enabled workbook (`.xlsm`) using `application/vnd.ms-excel.sheet.macroenabled.12`.

          '
        content:
          application/octet-stream:
            schema:
              description: 'The line-delimited JSON records within the client import request body represent either clients or relationships between clients.

                IMPORTANT: All relationship records must appear after all client records.

                '
              discriminator:
                propertyName: objectType
                mapping:
                  client: ./ClientImportJobRecordClient.yaml
                  relationship: ../../../../common/schemas/client/ClientRelationship.yaml
              oneOf:
              - description: A client record for import, including optional hash and assessmentRequired fields.
                allOf:
                - type: object
                  properties:
                    hash:
                      type: string
                      description: 'An optional hash of the client record. The hash is generated by the client and can be used to reconcile the version of the client stored in the system with versions mastered in the source system. When supplied during import, the hash can later be validated using the `/entity/validate-data` endpoint.

                        '
                    assessmentRequired:
                      type: boolean
                      default: false
                      description: 'When a client is loaded or updated, the assessmentRequired property of the client record can be set to true to request a full screening or re-screening of the Client against the risk data currently in the system at time of loading.

                        If this flag is not set, the client will be loaded or updated, but alerts will only be generated against the client as Risk Profiles and Internal Lists are loaded or updated in the system.

                        If the flag is set, the Client is screened against all existing Risk Profiles and List Entities and Alerts may be generated if any matches meet the alerting criteria in the Alert Policies.

                        '
                discriminator:
                  propertyName: entityType
                  mapping:
                    PERSON: ../../../../common/schemas/client/PersonClient.yaml
                    ORGANISATION: ../../../../common/schemas/client/OrganisationClient.yaml
                    VESSEL: ../../../../common/schemas/client/VesselClient.yaml
                    AIRCRAFT: ../../../../common/schemas/client/AircraftClient.yaml
                    UNKNOWN: ../../../../common/schemas/client/UnknownClient.yaml
                oneOf:
                - type: object
                  allOf:
                  - type: object
                    required:
                    - objectType
                    - entityType
                    - clientId
                    properties:
                      objectType:
                        type: string
                        enum:
                        - client
                      clientId:
                        type: string
                      entityType:
                        type: string
                        enum:
                        - PERSON
                        - ORGANISATION
                        - VESSEL
                        - AIRCRAFT
                        - UNKNOWN
                      name:
                        type: string
                        maxLength: 460
                        minLength: 1
                        description: 'The full name of the client. This is a key field used in identity matching.

                          The name can be provided either as name parts, depending on the client type (i.e. first name, middle name, surname in the case of person clients) or as a complete name using this field. If name parts are provided, the system will construct the full name from those parts.

                          Names cannot be longer than 460 characters (assuming UTF-8 encoding) or 975 bytes, and it is recommended that names do not exceed 400 characters to ensure that Identity Matching can be done efficiently. Titles and suffixes are not included in this limit.

                          '
                      status:
                        type: string
                        enum:
                        - ACTIVE
                        - INACTIVE
                      freeTextItems:
                        type: array
                        items:
                          type: object
                          properties:
                            fieldId:
                              type: string
                            value:
                              type: string
                          required:
                          - fieldId
                          - value
                      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
                      security:
                        type: object
                        description: 'The security attributes applied to this data item.

                          Labyrinth Screening applies Attribute-Based Security (ABAC) to some data items in the system, e.g. clients, alerts and attributes. These data items have security attributes defined that govern which users should have visibility of them. The rules governing this visibility are defined in the system''s security policy.

                          Systems can have different security policies, but the default policy compares the dataRolesN tags of a given user to the orTagsN tags of each data item. For a user to have visibility of a data item, they need to have at least one tag in their dataRolesN tags for each of the corresponding orTagsN tags of the data item.

                          '
                        properties:
                          enabled:
                            type: boolean
                            default: false
                          orTags1:
                            type: array
                            items:
                              type: string
                          orTags2:
                            type: array
                            items:
                              type: string
                          orTags3:
                            type: array
                            items:
                              type: string
                          andTags1:
                            type: array
                            items:
                              type: string
                          andTags2:
                            type: array
                            items:
                              type: string
                          andTags3:
                            type: array
                            items:
                              type: string
                          notTags1:
                            type: array
                            items:
                              type: string
                          notTags2:
                            type: array
                            items:
                              type: string
                          notTags3:
                            type: array
                            items:
                              type: string
                          compositeTags1:
                            type: array
                            items:
                              type: object
                              description: an object containing a set of security tags that should be considered together when making access control decisions
                          compositeTags2:
                            type: array
                            items:
                              type: object
                              description: an object containing a set of security tags that should be considered together when making access control decisions
                      lastReviewed:
                        type: string
                      fixedAlertSpans:
                        type: boolean
                        description: A flag to indicate that this client's alerts should transition to fixed-period alerts at the specified interval.
                        default: false
                      fixedAlertSpanPeriod:
                        type: string
                        description: The period alerts should cover at the point they transition to fixed-period alerts. Specified as an integer value followed by a time unit indicator (d=day, h=hour, y=year).
                        default: 1d
                      fixedAlertSpanStartDate:
                        default: the time the client is loaded
                        description: 'The time that that the initial fixed period alerting should start. When the fixed-period setting above are set or updated for a client, the start of the next review period for the client is calculated as follows: The  fixedAlertSpanStartDate is rounded up to the next midnight UTC and then offset by the number of minutes specified by alertingTimezone . When this initial alert period time is reached, the next review period is calculated by adding the fixedAlertSpanPeriod to this value.

                          '
                        type: string
                        format: date
                        example: '2023-12-25'
                      alertingTimezone:
                        type: integer
                        description: 'The timezone offset in minutes from midnight UTC that should be applied when calculating the start of each fixed alert period. For example, if alerts should transition to fixed period alerts at 03:00 UTC, the alertingTimezone should be set to 180.

                          '
                        default: 0
                      periodicReviewPeriod:
                        type: string
                      periodicReviewStartDate:
                        type: integer
                      identityNumbers:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                            value:
                              type: string
                          required:
                          - type
                          - value
                      bookingCenter:
                        type: string
                      segment:
                        type: string
                      businessRelationshipNumbers:
                        type: array
                        items:
                          type: string
                      businessRelationship:
                        type: array
                        items:
                          type: string
                      riskScore:
                        type: number
                      riskDescription:
                        type: string
                      employeeContactDetails:
                        type: object
                        properties:
                          name:
                            type: string
                          phoneNumber:
                            type: string
                    

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