Worldline Contract - Global Search API
Contract Global Search API Controller
OpenAPI Specification
swagger: '2.0'
info:
description: 'The current set of APIs will be available in Q2 2026 on Worldline Global Issuing Platforms.
Additional APIs are under construction and planned to be available in 2026.'
version: 2.41.1
title: Worldline Card Issuing Account - AccountState Contract - Global Search API
contact: {}
host: sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing
basePath: /api/v2
schemes:
- https
tags:
- name: Contract - Global Search
description: Contract Global Search API Controller
paths:
/search-contracts:
post:
tags:
- Contract - Global Search
summary: Global Search for Contracts
operationId: globalSearchContract
description: "The API provides possibility to retrieve a list of consumer contracts, based on certain criteria. \n\nOne of the following criteria for searching must be provided:\n- either account's criteria\n- or customer's criteria\n- or card's criteria\n\nFor searching with account's criteria, only one of the following data must be provided :\n•\tIBAN \n•\tor account identifier : either account reference or issuer account external reference\n•\tor account membership number 1\n•\tor account membership number 2 \n\nFor searching with customer's criteria, only one of the following data must be provided :\n•\tPersonal Data with last name and first name (and optionally with birth date, postal address : postal code, street name and/or building number, phonetic criteria)\n•\tor customer identifier : either customer reference or issuer customer external reference\n•\tor partner external reference\n\nFor searching with card's criteria, only one of the following data must be provided :\n•\tPAN\n•\tor card contract identifier : either card contract reference or issuer card contract external reference\n•\tor card identifier : either card reference or issuer card external reference\n\nIf requested, the API input parameters allows also to:\n* search from an issuer and optionally with sub-issuers OR search from a list of issuers (by default, the search is performed on all issuers allowed for the user depending on its rights)\n* limit the list of returned cards per card contract to either the latest card only or all previous cards\n* return the direct parent account in the hierarchy of the account and/or the list of child accounts of the account matching the criteria if the research is based on account's criteria\n* request to enrich the response with additional data relative to the accounts, the card contracts, the cards and the customers by using embedded fields\n\nThe API response contains all matched contracts and for each returned contract some information is provided such as\n- contract identifier with the contract reference, the issuer external contract reference if originally provided\n- product change information if any, such as its current status, new product, new contract if it exists\n- embedded fields if requested such as list of all customers or identifiers linked to this contract (e.g. contract owner, root account owner, cardholder(s)), accounts and account identifiers, card contracts, cards"
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- in: body
name: body
required: true
schema:
$ref: '#/definitions/GlobalSearchContractRequest'
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: page
in: query
description: '0'
required: false
type: integer
default: 0
format: int32
- name: offset
in: query
description: '10'
required: false
type: integer
default: 10
format: int32
- name: embed
in: query
description: Embedded Fields
required: false
type: array
items:
type: string
enum:
- advertisementFlags
- deliveryChannel
- legitimacyDocuments
- contractFees
- accountIdentifiers
- accounts
- accounts.selectedModels
- cardContractIdentifiers
- cardContracts
- cardContracts.cards
- dataAnalysisFlags
- contractCustomerIdentifiers
- contractCustomers
- addonSubscriptions
- contractCustomers.addresses
- cardContracts.relatedAccounts
- cardContracts.selectedModels
- cardContracts.cardIdentifiers
- cards.statusHistory
- cards.renewedBy
- cards.renewedFor
- cards.replacementBy
- cards.replacementFor
- cards.orderIdentifiers
- cards.orders
collectionFormat: multi
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityGlobalSearchContract'
security:
- basic: []
deprecated: false
definitions:
CustomerIdentifier:
type: object
description: Identification of the updated customer either by Issuer customer external reference or by customer reference
properties:
customerReference:
type: string
description: Reference computed internally by our system
issuerCustomerExternalReference:
type: string
description: Reference provided by the Issuer
title: CustomerIdentifier
CardIdentifier:
type: object
description: Identification of the card either by Issuer card external reference or by card reference
properties:
cardReference:
type: string
description: 'Reference of the card generated by our system, unique per platform.
This reference is calculated sequentially by an internal algorithm on 16 digits (e.g. 2000000000096013).'
issuerCardExternalReference:
type: string
description: 'External reference of the card provided by the issuer or calculated by the system if the external reference generation algorithm is configured for the issuer.
This reference is unique per issuer and may be used to carry out research and find information.'
title: CardIdentifier
Customer:
type: object
required:
- onlineRiskCategory
- offlineRiskCategory
properties:
issuerId:
type: string
description: Issuer identifier (unique per platform)
customerIdentifier:
description: Unique identifier. Refer to Customer Identifier data type for detail information
allOf:
- $ref: '#/definitions/CustomerIdentifier'
active:
type: boolean
description: DEPRECATED
birthDate:
type: string
format: date-time
description: Birth date of Person Customer (conditional depending on the card profile configuration). If present, the value can be subject to a validation process if a specific rule has been configured at issuer level.
birthPlace:
type: string
description: 'Birth Place of Person Customer (optional).
Free text'
commercialStatus:
type: string
description: Defines the commercial status of a Person Customer among a list of possible values configured per issuer. One of the possible values can be set as default value (eg. Normal, Address Only, Bankruptcy, Active Customer). (mandatory)
courtesyTitle:
type: string
description: Courtesy Title of Person Customer (optional). Free text. If present, the value can be subject to a validation process if a specific rule has been configured at issuer level.
customerClass:
type: string
description: for future use (optional)
doNotContact:
type: boolean
description: if the Person Customer does not want to be contacted by the issuer set to 'true' otherwise to be set to 'false'. If not provided, value is NULL(optional)
employee:
type: boolean
description: Flag indicating if the Person Customer is an employee of the issuer. If not provided, value is NULL(optional)
employerAddress:
type: string
description: 'Employer''s Address of Person Customer (optional).
Free text'
employerName:
type: string
description: 'Employer''s Name of Person Customer. (optional).
Free text'
firstName:
type: string
description: First Name of Person Customer (mandatory)
lastName:
type: string
description: Last Name of Person Customer (mandatory)
maidenName:
type: string
description: Maiden Name of Person Customer (optional)
correspondenceName:
type: string
description: Correspondence Name of Person Customer (optional).
maritalStatus:
type: string
description: Marital Status of Person Customer. Free text (optional)
monthlySalary:
type: string
description: Average monthly salary of Person Customer (optional)
nationality:
type: string
description: Nationality of Person Customer(optional). Free text.
offlineRiskCategory:
type: string
description: 'Categorizes the person for offline risk management. List of possible values is defined per Issuer (eg.Business, Student, Teenager, Standard). '
onlineRiskCategory:
type: string
description: 'Categorizes the person for online risk management. List of possible values is defined per Issuer (eg.Business, Student, Teenager, Standard) (mandatory) '
partnerExternalReference:
type: string
description: External Reference provided by the issuer (optional)
picture:
type: string
description: 'Picture reference of the Person Customer (eg url, filename). Free text.
(optional)'
preferredCorrespondanceLanguage:
type: string
description: Deprecated
preferredCorrespondenceLanguage:
type: string
description: Preferred correspondence language of the Person Customer (optional). Free text but ISO639-1 code is recommended (e.g. ‘nl’,’fr’,’de’,’en’). If present, the value can be subject to a validation process if a specific rule has been configured at issuer level.
profession:
type: string
description: 'Profession of Person Customer. Free text.
(optional)'
secondFirstName:
type: string
description: Second First Name of Person Customer (optional)
secretAnswer:
type: string
description: Answer to Secret Question for security (optional)
secretQuestion:
type: string
description: Secret Question for security (optional)
sex:
type: string
description: Gender of Person Customer (optional). Free text. If present, the value can be subject to a validation process if a specific rule has been configured at issuer level.
specificFields:
type: object
description: 'List of external data {"label":"value"} separated by a "," related to a customer that can be provided by e.g. the issuer for information or for usage by other systems. Example : {"label1":"value1","label2":"value2"} Those provided data have no impact on our system business processes.'
additionalProperties:
type: string
url1:
type: string
description: First URL of the Person Customer (optional)
url2:
type: string
description: Second URL of the Person Customer (optional)
vatCountry:
type: string
description: 'Tax country. Useful if Person is indeed a company.
(optional)'
vatNumber:
type: string
description: 'Tax number. Useful if Person is indeed a company.
(optional)'
addressIdentifiers:
type: array
description: 'List of active address references whatever their type (MAIL, EMAIL, PHONE). The address can be a temporary address if it is active at the time of the request.
At least, the main postal address reference should be retrieved (mandatory)
_Embedded property, only filled when available for the endpoint and explicitly requested in the ''embed'' query parameter._'
items:
$ref: '#/definitions/AddressIdentifier'
addresses:
type: array
description: 'List of active addresses whatever their type (MAIL, EMAIL, PHONE). See the Address''s datatype for the detail list of the attributes
_Embedded property, only filled when available for the endpoint and explicitly requested in the ''embed'' query parameter._'
items:
$ref: '#/definitions/Address'
vulnerabilities:
description: List of vulnerabilities applicable to the customer.
type: array
items:
$ref: '#/definitions/Vulnerability'
vulnerabilityIndicator:
type: boolean
description: indicates if the client is vulnerable
vulnerabilityNote:
type: string
description: note about the client's vulnerability (free text)
contactIdentifiers:
type: array
description: 'List of contact references of the customer.
_Embedded property, only filled when available for the endpoint and explicitly requested in the ''embed'' query parameter._'
items:
$ref: '#/definitions/ContactIdentifier'
contacts:
type: array
description: 'List of contacts of the customer.
_Embedded property, only filled when available for the endpoint and explicitly requested in the ''embed'' query parameter._'
items:
$ref: '#/definitions/Contact'
lastUpdateDate:
type: string
format: date-time
description: Indicates the date when the update is processed
title: Customer
ProductIdentifier:
type: object
properties:
issuerProductExternalReference:
type: string
description: Product External Reference provided by the issuer
productReference:
type: string
description: Reference of the product in our system, unique per platform
title: ProductIdentifier
GlobalSearchContractRequest:
type: object
properties:
issuerId:
type: string
description: 'The search is performed by default on all issuers allowed for the user (depending on its rights)
- The user can limit the search to one issuer (optional).
- If provided, the list of issuerIds must not be provided, otherwise the search is not performed (an error is generated).'
includeSubIssuers:
type: boolean
description: 'The user can request to include in the search the sub issuers of an issuer, limited to issuers allowed for the user depending on its rights, only if an issuerId is provided.
Default value is false.'
default: false
issuerIds:
description: 'The search is performed by default on all issuers allowed for the user (depending on its rights)
- The user can limit the search to a list of issuers (optional)
- If provided, the issuerId must not be provided, otherwise the search is not performed (an error is generated).
- If at least one issuer is not allowed for this user among the provided list of issuers, the search is not performed (an error is generated).'
type: array
items:
type: string
account:
description: "If the search is based on account's criteria, the issuer must provide only one of the following data: \n- iban of the account \n- account reference \n- issuer account external reference \n- account membership number 1 \n- account membership number 2"
allOf:
- $ref: '#/definitions/GlobalSearchContractRequestAccount'
customer:
description: "If the search is based on customer's criteria, the issuer must provide : \n- either personal data (with at least the first name and last name of the customer) or\n- customer identifier : customer reference or issuer customer external reference \n- or partner external reference"
allOf:
- $ref: '#/definitions/GlobalSearchContractRequestCustomer'
card:
description: "If the search is based on card's criteria, the issuer must provide only one of the following data: \n-PAN of the card \n-card Contract Reference \n-issuer Card Contract External Reference \n-cardReference \n-issuerCardExternalReference"
allOf:
- $ref: '#/definitions/GlobalSearchContractRequestCard'
retrieveParentAccount:
description: "Optional criteria to enrich the response. Can only be used if the search criteria refers to an account's criteria. \n If false (empty), only the account corresponding to the initial criteria will be returned. \n Else, the parent account in the hierarchy will be also returned (only the level n+1).\n Only applicable if the expendable params ‘Accounts’ or ‘AccountIdentifiers’ are requested.\n- Customer data response : based on the account found, every customers, owner of one of these accounts are returned in the response.\n- Card data response : based on the accounts found, every card contracts and their cards associated to one of these accounts are returned."
type: boolean
retrieveChildAccounts:
description: "Optional criteria to enrich the response. Can only be used if the search criteria refers to an account's criteria. \n If false (empty), only the account corresponding to the initial criteria will be returned. \n Else, the children accounts in the hierarchy will be also returned (only the level n-1). \n Only applicable if the expendable params ‘Accounts’ or ‘AccountIdentifiers’ are requested.\n- customer data response : based on the account found, every customers, owner of one of these accounts are returned in the response.\n- Card data response : based on the accounts found, every card contracts and their cards associated to one of these accounts are returned."
type: boolean
retrievePreviousCards:
description: Optional criteria to enrich the response. By default, the value is false. If true, all cards of the card contract will be retrieved in cardContracts.cards else only the latest card issued (by PAN) in card contract will be available in response (only used when embed field cardContracts.cards is requested)
type: boolean
title: GlobalSearchContractRequest
AccountStatusHistory:
type: object
properties:
status:
type: string
description: Status of the account on the particular statusDate (optional)
statusDate:
type: string
format: date-time
description: Date of the account status change (optional)
reason:
type: string
description: Reason the status has been set (optional)
title: AccountStatusHistory
InsurancePackageIdentifier:
type: object
description: Unique identifier of the insurance contract package
properties:
insurancePackageReference:
type: string
description: Reference of the insurance package
title: InsurancePackageIdentifier
CycleInformation:
type: object
description: Dates related to the closure calendar for the open closure cycle
properties:
cycleStartDate:
type: string
format: date-time
description: Date when the cycle is opened
cycleClosureDate:
type: string
format: date-time
description: Date when the open cycle is closed
statementGenerationDate:
type: string
format: date-time
description: Date when the statement is produced for the cycle
directDebitIssuingDate:
type: string
format: date-time
description: Direct debit issuing date of the cycle
directDebitDueDate:
type: string
format: date-time
description: Direct debit due date of the cycle
gracePeriodEndDate:
type: string
format: date-time
description: Grace period end date of the cycle
dueDateForSelfPayer:
type: string
format: date-time
description: Due date for self payer of the cycle
cycleDueDate:
type: string
format: date-time
description: Due date of the cycle, used for monitoring process (delinquency)
statementEffectiveStartDate:
type: string
format: date
description: "Effective start date of the statement period.\n\t\t\t\t\tExample :\n\t\tCycle closure is on 28th of each month at 20.00 PM\n\t\tIf closure on 28/08,\n\t\t- For August Statement: statementEffectiveStartDate = 29/07/2025 and statementEffectiveEndDate = 28/08/2025]\n\t\t- For September Statement : statementEffectiveStartDate = 29/08/2025 and statementEffectiveEndDate = 28/09/2025"
statementEffectiveEndDate:
type: string
format: date
description: "Effective end date of the statement period.\n\t\t\t\t\tExample :\n\t\tCycle closure is on 28th of each month at 20.00 PM\n\t\tIf closure on 28/08,\n\t\t- For August Statement: statementEffectiveStartDate = 29/07/2025 and statementEffectiveEndDate = 28/08/2025]\n\t\t- For September Statement : statementEffectiveStartDate = 29/08/2025 and statementEffectiveEndDate = 28/09/2025"
title: CycleInformation
ContractModel:
type: object
properties:
reference:
type: string
description: Model Reference
type:
type: string
description: 'Type of model
Possible values:
- ACCOUNT_SETUP_FEE
- MEMBERSHIP_FEE'
description: Model containing predefined configuration for fee generation applicable on a contract
title: ContractModel
EncryptedPan:
type: object
properties:
encryptedValue:
type: string
publicKeyIdentifier:
type: string
title: EncryptedPan
PinInheritanceExternalCardIdentifier:
type: object
properties:
pinInheritanceExternalCardReference:
type: string
description: Reference of the external card used when the card is only known by the PIN management module (used in migration context)
title: PinInheritanceExternalCardIdentifier
ContactIdentifier:
type: object
properties:
contactReference:
type: string
description: Contact identifier (unique per company)
title: ContactIdentifier
DataAnalysisFlags:
type: object
properties:
person:
type: boolean
description: Flag indicating person data related to the contract can be used for person data analysis (true) or not (false). Default value is false.
default: false
paymentTransaction:
type: boolean
description: Flag indicating if payment transactions related to the contract can be used for payment transactions data analysis (true) or not (false). Default value is false.
default: false
exchangeThirdParties:
type: boolean
description: Flag indicating if contract data can be exchanged between third parties (true) or not (false). Default value is false.
default: false
description: Specify which data analysis flags are enabled (person, paymentTransaction, exchangeThirdParties, etc.)
title: DataAnalysisFlags
Order:
type: object
properties:
issuerId:
type: string
description: Issuer identifier (unique per platform)
orderType:
type: string
description: 'The order can correspond to a card, a PIN mailer or a TAN mailer.
Possible values are : CardOrder, PinMailerOrder, TanMailerOrder'
orderIdentifier:
description: 'Unique identifier of the order (mandatory)
Refer to OrderIdentifier data type for detail information'
allOf:
- $ref: '#/definitions/OrderIdentifier'
currentExternalStatus:
type: string
description: 'Current external status of the order (optional)
The list of external statuses is configurable per issuer.
The external status can be used to follow the card producing status for the card order e.g. received, embossed, sent, etc.'
currentExternalStatusDate:
type: string
format: date-time
description: Modification date of the last external status of the order (optional)
currentInternalStatus:
type: string
description: 'Current internal status of the order (mandatory)
Possible values: are: CREATED, CONFIRMED, ORDERED, REJECTED, CANCELLED, FINISHED, ORDERABLE'
currentInternalStatusDate:
type: string
format: date-time
description: Last modification date of the internal status of the order (optional)
sendingMode:
type: string
description: 'Code identifying the desired sending mode for the order (mandatory)
Example: Normal, Urgent, Ultra Urgent'
deliveryChannel:
type: string
description: 'Code of the delivery channel for the card
The list of delivery channels is configurable per Issuer.'
deliveryType:
type: string
description: 'Indicates whether the delivery of the card should be to branch or customer (instead of the one from the distribution rule of the card product) (optional)
Possible values: CUSTOMER (the card is to be delivered to the customer address, BRANCH (the card is to be delivered to the bank branch)'
orderReason:
type: string
description: 'Reason why the order is done (mandatory)
Possible values are: CARD_RENEWAL, PIN_CARD_RENEWAL, FIRST_CARD_ISSUE, FIRST_PIN_CARD_ISSUE, CARD_REPLACEMENT, PIN_CARD_REPLACEMENT, PIN_REMINDER, PIN_REORDER, TAN_REQUEST'
statusHistory:
type: array
description: 'List of order status history data
Refer to OrderStatusHistory data type for detail information.
_Embedded property, only filled when available for the endpoint and explicitly requested in the ''embed'' query parameter._'
items:
$ref: '#/definitions/OrderStatusHistory'
cardProducer:
type: string
description: 'It is the card producer or embosser.
It is present if it is different than the default one (defined in the card profile) and was provided when requesting the card creation.
The list of allowed card producer is configurable per issuer.'
pinMailerEditor:
type: string
description: 'It is the PIN mailer printer.
It is present if it is different than the default one (defined in the card profile) and was provided when requesting the card/PIN creation.
The list of allowed PIN mailer editors is configurable by issuer.'
deliveryBranchCode:
type: string
description: 'Code of the delivery branch (mandatory only if card delivery type is BRANCH)
The list of issuer branches is configurable per Issuer.
The branch code is used to access a preconfigured Postal address (configured in the system).'
customDeliveryAddressee:
type: string
description: "Custom postal address to send the order \n Depending on countries, the address format (mainly for line1, line 2, line3, line4 and line5) can have specific conditions such as length restriction. The customer should contact WL to check the address format and have more information."
customDeliveryAddress:
description: 'Custom postal address to send the order
Depending on countries, the address format (mainly for line1, line 2, line3, line4 and line5) can have specific conditions such as length restriction. The customer should contact WL to check the address format and have more information.'
allOf:
- $ref: '#/definitions/MailAddress'
customDeliveryPhone:
description: 'Custom phone to send the card.
NOT USED'
allOf:
- $ref: '#/definitions/PhoneNumber'
customDeliveryEmail:
description: 'Custom email to send the card.
NOT USED'
allOf:
- $ref: '#/definitions/EmailAddress'
specificFields:
type: object
description: 'List of external data {"label":"value"} separated by a "," related to an order that can be provided by e.g. the issuer for information or for usage by other systems. Example : {"label1":"value1","label2":"value2"} Those provided data have no impact on our system business processes.'
additionalProperties:
type: string
card:
description: 'Card information related to the order.
_Embedded property, only filled when available for the endpoint and explicitly requested in the ''embed'' query parameter._'
allOf:
- $ref: '#/definitions/Card'
cardIdentifier:
description: Unique identifier of the card
allOf:
- $ref: '#/definitions/CardIdentifier'
embossingFileName:
type: string
description: Embossing file name in CardOrder
tanOrigin:
type: string
description: Origin of the TAN request, e.g. GUI. (free text)
tanBackupMethod:
type: string
description: The backup method that should be applied for TAN mailer order.
tanExpiryDate:
type: string
format: date-time
description: Expiry date of the TAN, date until which the TAN can used (mandatory for TanMailerOrder)
tanStatus:
type: string
description: 'Status of the TAN (mandatory for TanMailerOrder)
Possible values: CREATED, FAILED, ACTIVE, USED, EXPIRED'
freeTanMailerCounter:
type: integer
description: Number of free TAN requests (optional)
tanUsageDate:
type: string
format: date-time
description: Date when the TAN was used to change the PIN (optional)
free:
type: boolean
description: Indicates if the operation is free (true) or not (false). Default value is false (mandatory)
tanValue:
type: string
description: Clear value of the TAN (mandatory for TanMailerOrder)
feeConditions:
type: array
description: Conditions of the fee generation (if fee configured in the product) (optional)
items:
$ref: '#/definitions/FeeCondition'
notExtractedReason:
type: string
description: In case the order will not be extracted because of invalid customer address, then it will be indicated in this field
notExtractedUpdateDate:
type: string
format: date-time
description: The last update date of notExtractedReason field
waitingPin:
type: boolean
format: date-time
description: 'This flag is used only for a card order or a PIN mailer order.
- If this flag is true, the PIN is waiting to be provided by the cardholder (the mode “Self Selected Pin” is activated in the PIN production model). Depending on the configuration, after x days, the card is extracted with a default PIN if the cardholder has not provided a PIN.
- If this flag is false, the PIN is not waiting to be provided , e.g. the PIN has been generated by PMM or provided by the cardholder.'
title: Order
ForbiddenErrorApiResponse:
type: object
required:
- responseMetadata
properties:
respons
# --- truncated at 32 KB (160 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wordline/refs/heads/main/openapi/wordline-contract-global-search-api-openapi.yml