API basics
At Cross River, we have a robust set of APIs spanning our suite of products. To access our APIs and try them out in our sandbox, contact Integration Support to get started.
Our APIs are organized around REST, have object oriented URLs, accept form-encoded request bodies, return JSON-encoded responses, and use standard HTTP response codes, authentication, and methods.
When you call an API, you've sent a request. The answer you receive back is the response.
A resource (object) is the category of information that you want to receive information for, via API. For example, in our P2C product, a card and a transaction are resources, and in our lending product, a loan is a resource.
Endpoints and methods
- An endpoint is the URL address of an API that you want to retrieve. You can retrieve an endpoint by using a method.
- The method is the prefix you add to your endpoint to send the relevant API request. They are:
- GET A GET request retrieves resource information. A GET request never has a body.
- POST A POST request adds or creates a resource.
- PUT A PUT request updates or fixes resource information.
- DELETE A DELETE request deletes or cancels a resource.
- PATCH A PATCH request updates or fixes a smaller scope of resource information.
There are 3 types of parameters:
Path
A path parameter can be added to a URL endpoint to return a specific response. The path parameter is added to the URL in curly brackets ({ }) and follows a backslash (/).
For example, if you want to retrieve specific information on an account, you can add /{accountnumber} to the URL.
When your API includes curly brackets, a path parameter is required.
Body
Body parameters are the data included in the body of an API, and the information they represent can be changed. The body of the request and response messages are called payloads.
Query
A query parameter narrows down and filters the results of your request based on the information you are requesting. The query parameter is added to the URL and follows a question mark (?). Only GET calls use query parameters.
A request header is an HTTP header used in a request that provides information about the request context. It let's the server tailor the response.
In our documentation requests are presented in cURL.
Header | Description |
Authorization: {bearer token} | Authorization credentials for HTTP authentication. Include the bearer token in the Authorization header. |
Content-Type | Required for operations with a request body such as POST and PUT requests. The value is application/json indicating that the request body format is JSON.
|
Accept: application/json | Sets the output type to JSON. |
For every request, the response header contains a Request-ID value. This unique identifier is used by the Cross River Support Team for troubleshooting. We strongly recommend you save this identifier.
HTTP Code | Description |
1xx | Informational response. We received the request and processing continues |
2xx | Success. We successfully received, understood, and accepted the request |
200 | Success |
202 | We've accepted the request but need more time to process it |
3xx | Further action needs to be taken to complete the request |
4xx | The request contains bad syntax or cannot be fulfilled |
400 | There is something wrong with the data in your request or the request can't be processed |
401 | There is an issue with your API access token |
403 | Your token is good but you don't have permission to do what is being requested |
404 | The resource specified doesn't exist |
409 | The resource is in a conflicted state most likely due to simultaneous operations being performed. Your request should be retried. |
429 | Too many requests are being sent at once |
5xx | Server error. The server failed to fulfill an apparently valid request |
500 | Technical difficulties on our end |
When you're ready to start trying out our APIs and you've contacted customer support, they will send you a client ID and a password. After you're authorized into our system with the credentials, you'll receive an access token (a bearer token). Add the access token to your header, and you can then start calling our APIs.
You can send API requests using the command line with a tool such as cURL or by using a tool such as Postman.
With any tool that you use, you have to add information to the endpoint of a call.