Using the APIs

Capital One APIs are accessed through a RESTful interface and are designed to be easy to use.  The information below outlines the usage semantics and considerations you should fully understand before building an application.

Quick Navigation

• Customer Authorization
• Request and Response Formats
• Encryption Requirements
• Creating and API Request
• Parsing the Response
• Error Handling
• HTTP Response Codes

Customer Authorization

In order to make authorized API calls, your application must gain an Access Token which represents the customer.  Most likely, this will involve redirecting the user to our OAuth flow.  Alternatively, some use cases may require action on a user's account seamlessly without OAuth.  Our Identification API is designed for this scenario. You should review both approaches to understand the best option for your application.  Since the Identification API excludes the customer, usage must be fully understood and approved by Capital One.  You can contact us with any questions or details about how your application might use the Identification API.

Request and Response Formats

Our APIs use Form URL encoding (application/x-www-form-urlencoded) for passing request parameters when the inputs are simple (and do not have a hierarchy).  For cases when our APIs inputs are complex objects, multiple formats are supported.

Your application must select the desired format by using the HTTP "Accept" header.  Here are the supported formats:

Format	Mime Type
JSON	application/json
JSON (Encrypted)	application/json+enc (proprietary)
XML	text/xml
XML (Encrypted)	text/xml+enc (proprietary)

Encryption Requirements

In some cases, the request and/or response payloads must be encrypted using symmetric encryption for confidentiality.  Refer the Encryption API for how to obtain a symmetric key.  For encrypted payloads, your application must pass the data through a cipher (AES) prior to sending the request or processing the body of the response.  When handling the response, your application must inspect the Content-Type header in order to determine if decryption is required.  If you are using a framework (e.g. JAX-RS or .NET MVC API), you would need to develop a message body reader and writer to handle the processing automatically.

Creating and API Request

URI Format: https://api-sandbox.capitalone.com/[api]/[version]/[resource/method]

Example Request:

GET /deals/v1/list HTTP/1.1
Api-Key: [API key]
Authorization: bearer [Access Token]
Echo: [Echo token]
Accept: [Format]
Signature: nonce="[Nonce]", timestamp="[Timestamp]", method="HMAC-SHA256", signature="[Signature]"
User-Agent: [User agent]
Accept-Encoding: gzip, deflate

Where:

• API key is your API key.  This value is passed in a header instead of the query string to prevent it from being compromised.
• Access Token is the access token received from OAuth or the Identification API.  This is only applicable if you are calling a method that involves customer information (which most do).
• Echo token is an optional client generated identifier used to correlate asynchronous requests with their responses.  If this header is provided, it will be returned with the value the client provided.
• Format is the mime type of the desired output format as described above.
• Nonce is a randomly generated, alphanumeric token with a recommended length of 30 characters.
• Timestamp is the number of seconds since midnight, January 1, 1970 UTC.
• Signature is the SHA256 hash using the concatenated values (without delimiters) of:
  • Your API key
  • Your API secret
  • The nonce
  • The timestamp
• User agent is a string that includes the name of your application and version

The Accept-Encoding header is used to enable GZIP compression, which can greatly improve the performance of your application, especially if the user is connecting from a mobile device.

Parsing the Response

Our APIs will continue to evolve.  If we change data structure (e.g. hierarchy, field names), we will publish a new API version and maintain backwards compatiblity.  However, it is possible for new fields to become present in current APIs.  Therefore, if application uses a binding library to parse XML or JSON, it must ignore properties that are not present in your data classes.

For example, if you are using JAX-B for binding, there should be no exception thrown if an unknown property is encountered, however, if you are using Jackson for parsing JSON, throwing an excepiton is the default behavior.  If you are using Jackson, we recommend using one of these techniques for ignoring unknown properties.  Please refer to the documentation of the parser you are using for details on how unknown properties are handled.

Error Handling

Error information from our APIs are returned in a consistent manor for your application to be able to handle appropriately.  The message, type, and code fields should be interperited by your application in order to provide the best customer expirence when an error occurs.  Below are sample error responses in JSON and XML format.  Errors are never returned in an encrypted format.

JSON Sample Error

{
	"message" : "This request was not properly signed.",
	"type" : "AccessException",
	"code" : "SEC-0001"
}

XML Sample Error

<error>
	<message>This request was not properly signed.</message>
	<type>AccessException</type>
	<code>SEC-0001</code>
</error>

HTTP Response Codes

The table below lists the various HTTP status codes that can be encountered in the response.

Error Codes

You may find that using the code field is the easier way for your application to determine what went wrong.  Below is a table of codes and their meanings.