Getting started overview

Integrating with Citi's APIs provides access to a range of financial services, including payments, account information, and treasury management. This guide outlines the steps to get started with the Citi Developer Portal, focusing on account creation, obtaining credentials, and executing a foundational API request in the sandbox environment. The developer portal offers a free tier that includes a sandbox for testing, allowing developers to build and validate integrations before engaging for live environment access. Access to the live production environment typically involves a formal sales engagement process with Citi, which establishes the necessary commercial and security frameworks for handling real financial transactions.

Citi's API offerings are designed for enterprise-level integrations, supporting various financial workflows. The platform emphasizes security, compliance, and robust documentation to facilitate developer adoption. Key compliance standards include SOC 2 Type II for data security, GDPR for data privacy, and PCI DSS for payment card security, reflecting the requirements for financial sector operations. Developers should familiarize themselves with these standards as part of their integration planning.

Create an account and get keys

To begin using Citi's APIs, the first step is to create a developer account on the Citi Developer Portal. This account provides access to the sandbox environment, documentation, and API keys necessary for testing.

Account Creation Process

  1. Navigate to the Developer Portal: Go to the Citi Developer Portal registration page.
  2. Register: Click on the 'Sign Up' or 'Register' button. You will typically need to provide an email address, create a password, and agree to the terms of service.
  3. Verify Email: A verification email will be sent to the address you provided. Follow the instructions in the email to activate your account.
  4. Complete Profile: Log in to your new account and complete any required profile information. This may include company details or intended use cases for the APIs.

Obtaining API Keys and Credentials

Once your account is set up and verified, you can generate API keys and other necessary credentials within the developer portal. These credentials are vital for authenticating your requests to the Citi API sandbox.

  1. Access Dashboard: From your developer portal dashboard, locate the 'Applications' or 'My Apps' section.
  2. Create a New Application: Click to create a new application. You will likely be prompted to give your application a name and a brief description. This step helps organize your projects and API usage.
  3. Generate API Keys: Upon creating an application, the portal will typically generate a set of credentials. These often include:

    • Client ID (or API Key): A public identifier for your application.
    • Client Secret: A confidential key used to authenticate your application. Keep this secret secure and do not expose it in client-side code or public repositories.
    • Subscription Key: Some Citi APIs may use a subscription key model for specific API products.
  4. Note Credentials: Carefully record your Client ID and Client Secret. These are essential for making authenticated API calls. The Client Secret is often displayed only once upon generation for security reasons, so ensure you store it securely (e.g., in an environment variable or secure vault).

Citi's APIs often utilize OAuth 2.0 for authorization, which involves an additional step to obtain an access token using your Client ID and Client Secret. This access token is then included in subsequent API requests to authorize them.

Your first request

After obtaining your API keys, the next step is to make your first authenticated request to the Citi sandbox environment. We will demonstrate this using a common method: obtaining an OAuth 2.0 access token and then using it to call a sample API. For this example, we'll use cURL for its simplicity and universal availability, but the principles apply across other programming languages supported by Citi, such as Python, Java, and Node.js.

1. Obtain an Access Token

Most Citi APIs require an OAuth 2.0 access token. This token is typically acquired by sending a POST request to an authorization endpoint with your Client ID and Client Secret.

CLIENT_ID="YOUR_CLIENT_ID"
CLIENT_SECRET="YOUR_CLIENT_SECRET"

curl -X POST "https://sandbox.developer.citi.com/oauth/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET"

Upon successful execution, the API will return a JSON response containing your access_token and its expires_in duration. Extract the access_token from this response.


{
  "access_token": "YOUR_GENERATED_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "some_scope"
}

2. Make a Sample API Call

With your access_token, you can now make an authenticated request to a sandbox API endpoint. A common starting point is an Account Information API, such as listing available accounts (though specific endpoints may vary based on API product and developer access).

ACCESS_TOKEN="YOUR_GENERATED_ACCESS_TOKEN"

curl -X GET "https://sandbox.developer.citi.com/api/v1/accounts" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json"

Replace /api/v1/accounts with an actual sandbox endpoint from the Citi API Reference that you have access to. A successful response will typically return a 200 OK status code and a JSON payload relevant to the requested data, such as a list of dummy accounts in the sandbox.


[
  {
    "accountId": "123456789",
    "accountNickname": "Sandbox Checking",
    "currency": "USD",
    "currentBalance": {
      "amount": 10000.00,
      "currency": "USD"
    }
  },
  {
    "accountId": "987654321",
    "accountNickname": "Sandbox Savings",
    "currency": "USD",
    "currentBalance": {
      "amount": 50000.00,
      "currency": "USD"
    }
  }
]

This sequence confirms that your credentials are set up correctly and you can successfully interact with the Citi sandbox environment.

Common next steps

After successfully making your first API call in the sandbox, consider these next steps to deepen your integration and prepare for production:

  1. Explore More APIs: Review the full Citi API Reference to understand the breadth of available services, including Payment APIs, Treasury APIs, and FX APIs. Identify the specific endpoints relevant to your application's use case.
  2. Read Documentation Thoroughly: The developer documentation provides detailed information on request/response structures, error codes, and specific API behaviors. Pay close attention to data formats and required headers.
  3. Implement Error Handling: Design your application to gracefully handle API errors, including rate limits, authentication failures, and validation errors. Understanding Citi's error code conventions is crucial.
  4. Integrate SDKs (if available/preferred): While Citi's developer portal does not list official SDKs, developers often build their own client libraries. If you prefer using SDKs, consider developing a wrapper around the API for your chosen programming language (e.g., Python, Java, Node.js) to streamline integration.
  5. Security Best Practices: Implement robust security measures for handling API keys and sensitive data. This includes using environment variables for credentials, secure storage, and adhering to OAuth 2.0 best practices for token management, as outlined in the OAuth 2.0 Bearer Token Usage specification.
  6. Plan for Production Access: Understand the requirements for moving from the sandbox to the live production environment. This typically involves a formal engagement with Citi's sales team, including due diligence processes, legal agreements, and technical reviews.
  7. Monitor API Usage: As you develop, consider how you will monitor your API usage, performance, and potential issues in both sandbox and eventually production environments.

Troubleshooting the first call

When making your first API call, you might encounter common issues. Here’s a guide to troubleshoot them:

Problem What to Look For Solution
401 Unauthorized Incorrect Client ID/Secret, expired access token, missing Authorization header.
  • Double-check your Client ID and Client Secret for typos.
  • Ensure your access token is still valid (check expires_in).
  • Verify the Authorization: Bearer YOUR_ACCESS_TOKEN header is correctly formatted and present in your request.
  • Regenerate your access token if it has expired or if you suspect it's invalid.
403 Forbidden Insufficient permissions, incorrect API scope, IP whitelist restrictions.
  • Confirm your application has the necessary permissions for the requested API endpoint in the developer portal.
  • Ensure the access token was generated with the correct scopes for the API you are trying to call.
  • If applicable, check if your IP address needs to be whitelisted for sandbox access.
400 Bad Request Malformed JSON/request body, missing required parameters, invalid data types.
  • Review the API Reference for the specific endpoint to ensure all required parameters are included and correctly formatted.
  • Validate your JSON payload for syntax errors.
  • Check that content type headers (e.g., Content-Type: application/json) match your request body.
404 Not Found Incorrect endpoint URL, API version mismatch.
  • Verify the API endpoint URL against the Citi API Reference, including the base URL (e.g., sandbox.developer.citi.com) and version number (e.g., /v1/).
  • Ensure you are targeting the sandbox environment for initial testing.
5xx Server Error Internal server issues on Citi's side, temporary service unavailability.
  • These usually indicate an issue on the API provider's side.
  • Wait a few minutes and retry the request.
  • Check the Citi Developer Portal for any service status updates or announcements.
  • If the problem persists, contact Citi Developer Support.

Always review the full error response body, as it often contains specific details that can help pinpoint the exact issue. The Citi Developer Portal documentation is the primary resource for detailed error codes and troubleshooting guides.