You can use the API to search certain item types for matches. Useful when you do not know the RevCent ID of an item. API search is a means to find a specific item using a string term, such as finding a customer or sale by email.
The search method was introduced as a way for third parties or apps to quickly retrieve results based on a search term for an item type. Only certain fields are searched by RevCent, and only a small subset of fields are returned for each match. Use the id field in matches to then conduct a retrieve request for detailed information on the match.
Note: At this time, searches are limited to 10 max results, without pagination or filters.
Unlike the API retrieve request, the search method is limited to specific item types. Also, each item type is limited in the fields that are searched within.
For instance, you can search a transaction by first 6 digits of the card used, but cannot search for a transaction using a customers' email.
The item types that are currently supported, along with searchable fields, are listed below.
The tables below outline the search fields and response fields for the customer item type.
| Field | Description |
|---|---|
| id | The RevCent ID of the customer. |
| first_name | The first name of the customer. |
| last_name | The last name of the customer. |
| address_line_1 | The customers address line 1. |
| The customers' email address. | |
| internal_id | The customers' internal_id. |
| ip_address | The IP address of the customer. |
| phone | The customers' phone number. |
| fingerprint | The tracking fingerprint of the customer. |
| metadata | All metadata values within a customer. |
| Field | Description |
|---|---|
| id | The RevCent ID of the customer. |
| created_date_unix | The unix timestamp when the customer was created. |
| first_name | The first name of the customer. |
| last_name | The last name of the customer. |
| address_line_1 | The customers address line 1. |
| address_line_2 | The customers address line 2. |
| city | The customers address city. |
| state | The customers address state. |
| zip | The customers address zip. |
| The customers' email address. | |
| phone | The customers' phone number. |
| internal_id | The customers' internal ID. |
| ip_address | The IP address of the customer. |
| enabled | Whether the customer is enabled in RevCent. |
| fingerprint | The tracking fingerprint of the customer. |
| metadata | The customers' metadata. |
| url | The url to the customers' details page in RevCent |
The tables below outline the search fields and response fields for the sale item type.
| Field | Description |
|---|---|
| id | The RevCent ID of the sale. |
| first_name | The first name of the customer. |
| last_name | The last name of the customer. |
| address_line_1 | The customers address line 1. |
| The customers' email address. | |
| phone | The customers' phone number. |
| ship_to_first_name | The ship to first name for the sale. |
| ship_to_last_name | The ship to last name for the sale. |
| ship_to_address_line_1 | The ship to address line 1. |
| ip_address | The IP address of the customer. |
| fingerprint | The tracking fingerprint of the customer. |
| metadata | All metadata values within a sale. |
| Field | Description |
|---|---|
| id | The RevCent ID of the sale. |
| created_date_unix | The unix timestamp when the sale was created. |
| first_name | The first name of the customer. |
| last_name | The last name of the customer. |
| address_line_1 | The customers address line 1. |
| address_line_2 | The customers address line 2. |
| city | The customers address city. |
| state | The customers address state. |
| zip | The customers address zip. |
| The customers' email address. | |
| phone | The customers' phone number. |
| ship_to_first_name | The ship to first name. |
| ship_to_last_name | The ship to last name. |
| ship_to_address_line_1 | The ship to address line 1. |
| ship_to_address_line_2 | The ship to address line 2. |
| ship_to_city | The ship to address city. |
| ship_to_state | The ship to address state. |
| ship_to_zip | The ship to address zip. |
| ip_address | The IP address of the customer. |
| fingerprint | The tracking fingerprint of the customer. |
| metadata | The sales' metadata. |
| url | The url to the sale' details page in RevCent |
The tables below outline the search fields and response fields for the shipping item type.
| Field | Description |
|---|---|
| id | The RevCent ID of the shipment. |
| ship_to_first_name | The ship to first name for the shipment. |
| ship_to_last_name | The ship to last name for the shipment. |
| ship_to_address_line_1 | The ship to address line 1. |
| provider_tracking | The shipment tracking number. |
| metadata | All metadata values within a shipment. |
| Field | Description |
|---|---|
| id | The RevCent ID of the shipment. |
| created_date_unix | The unix timestamp when the shipment was created. |
| ship_to_first_name | The ship to first name for the shipment. |
| ship_to_last_name | The ship to last name for the shipment. |
| ship_to_address_line_1 | The ship to address line 1. |
| ship_to_address_line_2 | The ship to address line 2. |
| ship_to_city | The ship to address city. |
| ship_to_state | The ship to address state. |
| ship_to_zip | The ship to address zip. |
| provider | The shipping provider. |
| provider_method | The shipping provider method. |
| provider_tracking | The shipment tracking number. |
| shipping_status | The current shipping status. |
| ship_date_unix | The unix timestamp when the shipment was shipped, if shipped. |
| delivered_date_unix | The unix timestamp when the shipment was delivered, if delivered. |
| metadata | All metadata values within a shipment. |
| url | The url to the shipments' details page in RevCent |
The tables below outline the search fields and response fields for the transaction item type.
| Field | Description |
|---|---|
| id | The RevCent ID of the transaction. |
| first_6 | The first 6 digits of the credit card used. |
| last_4 | The last 4 digits of the credit card used. |
| gateway_transaction_id | The gateway transaction ID. |
| metadata | All metadata values within a transaction. |
| Field | Description |
|---|---|
| id | The RevCent ID of the transaction. |
| created_date_unix | The unix timestamp when the transaction was created. |
| customer_id | The RevCent ID of the customer related to the transaction. |
| first_name | The first name of the customer related to the transaction. |
| last_name | The last name of the customer related to the transaction. |
| The email of the customer related to the transaction. | |
| card_id | The RevCent ID of the credit card related to the transaction. |
| first_6 | The first 6 digits of the credit card used. |
| last_4 | The last 4 digits of the credit card used. |
| gateway_transaction_id | The gateway transaction ID. |
| request_type | The request type that created the transaction. |
| request_method | The request method that created the transaction. |
| approved | Whether or not the transaction was approved. |
| metadata | All metadata values within a transaction. |
| url | The url to the transactions' details page in RevCent |
The most common method for searching is to supply a single search_term, which tells RevCent to search all available fields for the item type using the single search_term.
In the example below, we are searching customers using the top level search_term property. When using the top level search_term method, RevCent will search all fields listed for customer.
{
"request": {
"type": "customer",
"method": "search",
"search_term": "xbim32@gmail.com"
}
}RevCent will search all customer fields for a match using xbim32@gmail.com as the search phrase.
In the example API response below, we received the results from searching the customer via all fields. Notice how the result highlights the email field as it was the field that matched the search_term.
Get more details on the customer by conducting a retrieve request using a matches' id field.
{
"api_call_id": "MWazbqOmazHZ5QnERONV",
"api_call_processed": true,
"api_call_unix": 1681160039,
"code": 1,
"request_type": "customer",
"request_method": "search",
"results": [
{
"item_type": "customer",
"id": "gYQYYJlMXYHXXL709WlR",
"created_date_unix": 1680909458,
"first_name": "zqhy",
"last_name": "tyxpeqkk",
"address_line_1": "1600 Pennsylvania Ave",
"address_line_2": "",
"city": "Washington",
"state": "DC",
"zip": "20500",
"email": "xbim32@gmail.com",
"phone": "1234567890",
"internal_id": "",
"ip_address": "123.456.789.0",
"enabled": true,
"fingerprint": "40ffd9fe03525794d84b3c583625e622",
"metadata": [],
"url": "https://revcent.com/user/customer-details/gYQYYJlMXYHXXL709WlR",
"highlights": [
{
"field": "email",
"values": [
"xbim32@gmail.com"
]
}
],
"score": 7.68
}
]
}
You may want to search only specific fields and not all fields at once. For example, if you know you are searching using an email address and first_name, then you may find the best match by searching only those fields. Instead of using the top level search_term string, you use the search_fields array.
In the example below, we are searching the first_name and email fields of the customer. The search_fields array contains one or more search field objects. Each search field object contains a field and search_term. RevCent will only search the fields provided in the search_fields array.
{
"request": {
"type": "customer",
"method": "search",
"search_fields": [
{
"field": "first_name",
"search_term": "zqhy"
},
{
"field": "email",
"search_term": "xbim32@gmail.com"
}
]
}
}RevCent will search the first_name field using the term zqhy as well as the email field using the term xbim32@gmail.com. RevCent will not search other customer fields such as last_name, phone, etc.
In the example API response below, we received the results from searching the customer using the search_fields array. Notice how the result highlights include both first_name and email fields as they both matched respectively.
Get more details on the customer by conducting a retrieve request using a matches' id field.
{
"api_call_id": "nbpBMazqvaH6ZQa0yOb2",
"api_call_processed": true,
"api_call_unix": 1681211066,
"code": 1,
"request_method": "search",
"request_type": "customer",
"results": [
{
"item_type": "customer",
"id": "gYQYYJlMXYHXXL709WlR",
"created_date_unix": 1680909458,
"first_name": "zqhy",
"last_name": "tyxpeqkk",
"address_line_1": "1600 Pennsylvania Ave",
"address_line_2": "",
"city": "Washington",
"state": "DC",
"zip": "20500",
"email": "xbim32@gmail.com",
"phone": "4041242229",
"internal_id": "",
"ip_address": "166.182.250.169",
"enabled": true,
"metadata": [],
"url": "https://revcent.com/user/customer-details/gYQYYJlMXYHXXL709WlR",
"highlights": [
{
"field": "email",
"values": [
"xbim32@gmail.com"
]
},
{
"field": "first_name",
"values": [
"zqhy"
]
}
],
"score": 13.167387008666992
}
]
}
There are two additional fields, highlights and score, provided for each match in the results array. Both fields are useful for determining the best match, as well as the match differences.
Every match will return a highlights array. The highlights array shows the fields that match the search_term(s). This is useful for visual display as well as knowing what fields matched what search term.
Every match will return a score. The score is determined by the search engine. The results array is always sorted by score descending.