Search
Search API Method
This operation is used to search by various parameters to retrieve the Account/Card Status Info. Only one of three options below should be used to perform search. Combination search is not supported.
• AccountNumber
• PhoneNumber
• Combination of IdentityType, IdentityNumber and IssuerCountryCode
Every request triggered should have a unique X-GD-RequestId value in the header.
Syntax
POST {baseUrl}/search
Example Request
Success Request
POST {baseUrl}/search
Authorization: bearer {token}
Content-Type: application/json
X-GD-RequestId: test101
{
"phoneNumber": "",
"accountNumber": "",
"identityType": "ITIN",
"identityNumber": "930471923",
"issuerCountryCode": "",
"metadata": {
"storeId": "CC970",
"merchantId": "FSCC0342",
"userId": "[email protected]",
"requestDateTime": "2023-09-28T09:32:32Z",
"registerId": ""
}
}
Negative Request
POST {baseUrl}/search
Authorization: bearer {token}
Content-Type: application/json
X-GD-RequestId: test101
{
"phoneNumber": "123",
"accountNumber": "",
"identityNumber": "",
"identityType": "",
"issuerCountryCode": "",
"metadata": {
"storeId": "CC970",
"merchantId": "FSCC0342",
"userId": "[email protected]",
"requestDateTime": "2023-09-28T09:06:53Z",
"registerId": "01"
}
}
Request Parameters
| Parameter | Required (Y/N) | Format/ Data Type | Pattern | Description |
|---|---|---|---|---|
| X-GD-RequestId | Yes | String | MaxLength:50 | It is a unique transaction identifier that is generated by the retailer. |
| requestDateTime | Yes | DateTime | 2023-08-08T12:34:56Z | Time stamp at which transaction occurred. The time stamp has to be in UTC time zone and follow the following date and time formats: • YYYY-MM-DDTHH:mm:ssZ |
| registerId | No | String | MaxLength: 20 | Register where the transaction occurred. |
| userId | Yes | String | MaxLength:50 | The unique ID of the user generating the transaction. If not supplied, InvalidParameter (Code:100) error will be return. |
| storeId | Yes | String | MaxLength: 20 | The store number associated with the retailer that sold the package. If not supplied, InvalidParameter (Code:100) error will be return. |
| merchantId | Yes | String | MaxLength: 20 | Unique merchant Id. It is defined by Green Dot – Merchant corresponding with Retailer. If not supplied, InvalidParameter (Code:100) error will be return. |
| phoneNumber | No | String | 10 digits | PhoneNumber that is used to search account. PhoneNumber has to be 10 digits |
| identityType | No | String | Min: 3 , Max: 21 | Values can be SSN, Passport, ITIN and NationalIdCard. Note that Mexican Matricula use nationalIdCard as Type. |
| identityNumber | No | String | Min: 1 , Max: 50 | Identity Document Number value for the Identity Type. Only numbers and alphabets are allowed in IdentityNumber field. |
| issuerCountryCode | No | String | Min: 3 | Country that issued the identification card in ISO 3166-1 alpha-3 format. Note: For any given identity type, issuecountrycode field is mandatory. Possible values are USA, COL, CUB, DOM, ECU, SLV, GTM, HND, MEX, NIC and VEN. |
| accountNumber | No | String | 16 digits PAN | Account Number (PAN) of the card. |
Example Response
Success Response
HTTP/1.1 200 OK
Content-Type: application/json
X-GD-RequestId: test101
X-GD-ResponseId: 9c829539-7dfb-41d8-b536-1f25a63d240d
X-GD-ResponseCode: 0
{
"info": [
{
"cardStatus": "activated",
"accountStatus": "normal",
"lastFourAccountNumber": "9091",
"accountIdentifier": "06e33e98-5c40-4c1a-967b-930f28f509a4",
"phoneNumber": "2436755891",
"name": "Approved ITbOJjNV",
"lastFourIdentityNumber": "1923"
}
],
"metadata": {
"requestId": "test101",
"responseId": "9c829539-7dfb-41d8-b536-1f25a63d240d",
"responseDateTime": "2023-09-28T09:08:27.7781206Z",
"responseCode": 0,
"responseDescription": "Success"
}
}
Negative Response
HTTP/1.1 400 OK
Content-Type: application/json
X-GD-RequestId: test101
X-GD-ResponseId: 566561b7-1082-4b90-9ab3-fd2bc3878095
X-GD-ResponseCode: 100
{
"info": null,
"metadata": {
"requestId": "test101",
"responseId": "566561b7-1082-4b90-9ab3-fd2bc3878095",
"responseDateTime": "2023-09-28T09:10:29.9634977Z",
"responseCode": 100,
"responseDescription": "PhoneNumber has to be 10 digits"
}
}
Response Parameters
| Parameter | Required (Y/N) | Format/Data Type | Pattern | Description |
|---|---|---|---|---|
| requestId | Yes | String | MaxLength:50 | The unique request ID generated from the request. |
| responseId | Yes | String | MaxLength:50 | The unique Response Identifier (generated by GreenDot |
| responseDateTime | Yes | DateTime | 2023-09-07T16:12:23.4541445+08:00 | Time stamp at which transaction occurred. The time stamp is in UTC time zone and follow the following date and time formats: • YYYY-MM-DDTHH:mm:ssfffffffK |
| responseCode | Yes | Numeric | MaxLength:4 | Indicates success and failure of the response codes. It is in the numeric format. |
| responseDescription | Yes | String | MaxLength:255 | Describes the Response Code in more detail. It is in the String format. |
| info | Yes | String | List of Account/Card Info Status. This field will be null if no record is found or validation failed. | |
| cardStatus | String | activated notActivated blocked Closed | Fixed value indicating card activation status. | |
| accountStatus | String | pending normal restricted closed locked | Fixed value indicating Account Status. | |
| lastFourAccountNumber | String | 4 digits | Last Four Account Number (PAN). | |
| accountIdentifier | String | e5843e05-d367-4bf1-a223-3af46ae18802 | Can be used for other API calls. | |
| phoneNumber | String | 7648329876 | Phone number registered for the account. | |
| name | String | Jack Bauer | Cardholder Name of the account. | |
| lastFourIdentityNumber | String | 9687 | Last 4 Digits SSN or other Identity type value. |
Response Cases
| Code | CodeText | Response Description | Description |
|---|---|---|---|
| 0 | Success | Success | Success |
| 100 | InvalidParameter | • Invalid parameters • PhoneNumber has to be 10 digits • Only numbers and alphabets are allowed in IdentityNumber field • MerchantId is required • StoreId is required • UserId is required • RequestId is required • RequestDateTime is required • RequestId is too long • UserId is too long • StoreId is too long • MerchantId is too long • AccountNumber has to be 16 digits • Invalid ssn format • IssuerCountryCode has to be 3 alphabets | Invalid parameter in the request. Examples: MerchantID not supplied, StoreID not supplied. |
| 130 | InvalidMerchant | InvalidMerchant | MerchantId in request has not been found/enabled in the system. |
| 800 | InvalidStore | Store was not found | Store is not found, store is not for the partner or store does not support this operation. |
| 815 | AccountNotFound | AccountNotFound | Account not found |
| 861 | RetailChainUserNotFound | User is not found. | UserID in request is not found in system. |
| 862 | RetailChainUserNotActive | User is not active. | UserId in request is not active. |
| 1000 | GeneralFailure | GeneralFailure | Service failure. |
Updated 16 days ago