Worldline Corporate Contract - Global Search API
Corporate 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 Corporate Contract - Global Search API
contact: {}
host: sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing
basePath: /api/v2
schemes:
- https
tags:
- name: Corporate Contract - Global Search
description: Corporate Contract Global Search API Controller
paths:
/search-corporate-contracts:
post:
tags:
- Corporate Contract - Global Search
summary: Search corporate contracts
operationId: searchCorporateContracts
description: "The API provides possibility to retrieve a list of corporate contracts, based on certain criteria.\n\nOnly one of the following criteria for searching must be provided:\n* the corporate name and optionally company postal address information (street name, building number, zip code).\n* or the reference of the company : it can be provided by using the customer reference or the issuer customer 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* retrieve contract owner information\n* request to enrich the response with additional data relative to the root account, the companies, the current addresses of the companies, the corporate contract entities and the corporate employee accounts by using embedded fields\n\nThe API response contains all matched corporate contracts and for each returned corporate contract some information is provided such as\n•\tcontract identifier with the contract reference, the issuer external contract reference if originally provided\n•\tembedded fields if requested such as root account, list of all companies (limited to 100) with their addresses linked to this corporate contract, corporate contract entities(limited to 100), corporate employee accounts(limited to 100)."
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
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: embed
in: query
description: Embedded Fields
required: false
type: array
items:
type: string
enum:
- rootAccount
- contractCompanies
- contractCompanies.addresses
- corporateContractEntities
- corporateEmployeeAccounts
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
- in: body
name: body
required: true
schema:
$ref: '#/definitions/GlobalSearchCorporateContractRequest'
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/ApiResponseEntityListCorporateContracts'
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
CorporateContractFee:
type: object
allOf:
- $ref: '#/definitions/ContractFee'
- properties:
entityIdentifierMembershipFeePosting:
description: The corresponding entity identifier for Membership Fee posting
allOf:
- $ref: '#/definitions/FeePostingEntityIdentifier'
entityIdentifierAccountSetupFeePosting:
description: The corresponding entity identifier for Account Setup Fee posting
allOf:
- $ref: '#/definitions/FeePostingEntityIdentifier'
description: Specify the corporate contract Fee
title: CorporateContractFee
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
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
GlobalSearchCorporateContractRequestPostalAddress:
type: object
properties:
streetName:
type: string
description: 'The street name where is located the company.
This criteria is optional and accept wildcards (''%'' allows to achieve a search with only a partial input, ''Plat%'', ''%hill'', ''Al%gang'')'
buildingNumber:
type: string
description: 'The building number where is located the company.
This criteria is optional and accept wildcards (''%'' allows to achieve a search with only a partial input, ''12t%'', ''%4bll'')'
postCode:
type: string
description: 'The postal code where is located the company.
This criteria is optional and accept wildcards (''%'' allows to achieve a search with only a partial input, ''91%'', ''%41l'')'
title: GlobalSearchCorporateContractRequest.PostalAddress
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:
responseMetadata:
allOf:
- $ref: '#/definitions/ForbiddenResponseMetadata'
title: ForbiddenErrorApiResponse
GlobalSearchCorporateContractRequest:
type: object
required:
- contractCompany
properties:
contractCompany:
type: object
description: The issuer must provide some information related to the company to filter the corporate contracts to be returned.
allOf:
- $ref: '#/definitions/GlobalSearchCorporateContractRequestCompany'
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:
type: array
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).'
items:
type: string
retrieveContractOwner:
type: boolean
description: "Optional parameter to enrich the information retrieved.\n If the parameter is set to true, the contract owner will be retrieved in the list of companies.\n If the embed parameter contractCompanies is not requested and the parameter is set to true, an error will be raised."
title: GlobalSearchCorporateContractRequest
Card:
type: object
required:
- issuerId
properties:
issuerId:
type: string
description: Issuer identifier (unique per platform)
cardIdentifier:
description: Identification of the card either by Issuer card external reference or by card reference
allOf:
- $ref: '#/definitions/CardIdentifier'
encryptedPan:
description: This field returns the encrypted PAN and the public key identifier if the encryption is activated on the platform.
allOf:
- $ref: '#/definitions/EncryptedPan'
pan:
type: string
description: "Primary Account Number (PAN) also called card number (mandatory) \n It is calculated by our system from the BIN range associated to the card product or provided by the issuer."
maskedPan:
type: string
description: "Masked Primary Account Number (PAN) of the card (optional). \nExample: 445442******0275\nThe mask is defined per platform."
panReference:
type: string
description: "Reference related to the PAN\nCards having the same PAN have the same PAN reference.\nPAN reference is generated in the system according to the following algorithm : \n1 (VISA) or 2 (MCI) + 3 last digit of issuer + UUID (without the -)\nExample : 1006f041ae6814bf4f068aa501141c85d57d"
expiryDate:
type: string
description: 'Card expiry date (mandatory)
Format is MMYY (month and year)'
panSequenceNumber:
type: string
description: PAN sequence number is a number (usually from 1 to N) that allows identifying either cards with same PAN or cards with same PAN and same Expiry date
status:
type: string
description: "Current status of the card (mandatory) \n Possible values: CREATED, ACTIVE, BLOCKED, DEACTIVATED, CANCELLED\n Status of the card (mandatory)\n The card status is changing during its life cycle according to business processes in the system.\n Possible values are :\n CREATED : The first status when the card is created. The card is not usable.\n ACTIVE : Card is active and ready for authorizations processing\n Examples of business processes triggering this status: contract creation request as per product configuration, card activation request, contract creation after a product change request.\n BLOCKED : card is blocked permanently (final status) or temporarily. Related authorizations are declined.\n DEACTIVATED : Card is deactivated (final status) and related authorizations are declined\n Examples of business processes triggering this status: contract closing request, card contract closing, contract closure after a product change request. Card was in ACTIVE status previously.\n CANCELLED : Card is cancelled (final status). Card has never been activated.\n Examples of business processes triggering this status: contract closing request, card contract closing, contract closure after a product change request. Card was in CREATED status previously."
statusDate:
type: string
format: date-time
description: Last card status change date (mandatory)
externalS
# --- truncated at 32 KB (155 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wordline/refs/heads/main/openapi/wordline-corporate-contract-global-search-api-openapi.yml