Getting Started with ExxonMobil APIs
Introduction ↑ Back to top
APIs have become key components of business innovation and collaboration across many industries. The ExxonMobil Developer Hub provides a convenient, easy-to-use resource for sharing our APIs with our customers, suppliers, and third-party service providers.
Getting started on the ExxonMobil Developer Hub is quick, easy, and free. This guide provides all the information you need.
Create an Account ↑ Back to top
To access our API specifications and documentation, you’ll need to create an account on our Hub. Just follow these steps:
1. Click on Sign up, located in the top right corner of the page.
2. Enter the required information.
3. Review and accept EM API Terms of Use.
4. Click the Sign Up button.
5. You will receive an email with a link to activate your new account. Click on this and set up your password. Once your account is activated, you may follow instructions in Log In section below to access the API Developer Hub.Log In ↑ Back to top
To access the API Developer Hub:
1. Open your internet browser, navigate to https://developer.exxonmobil.com, and click the "Login" link.
2. You will be directed to https://apihub.exxonmobil.com. Use the button on the page “External User Login”.
3. Enter the email address and password that you provided when following instructions above to create your API Developer Hub account.
Start Exploring! ↑ Back to top
APIs relevant to your account will be visible on the Hub upon login.
If you don't find the specific API you're looking for, please use search field at the top of the screen.
You may filter your search by:
• Category – search APIs based on a common characteristic.
• Collections – search APIs by persona, for example, Customers / Distributors, Service Providers, Raw Material Suppliers, etc.
• Tags – search APIs based on custom attributes, for example, chemical (APIs developed for chemical customers, 3PSPs, suppliers etc. of ExxonMobil), warehouse (APIs developed for warehouse service providers), etc.
Once you receive your search results, select an API to visit the documentation page and learn more.
API Listing Overview ↑ Back to top
Every API has a documentation page where you will find most of the information you need to get started, including:
• Navigation.
• A list of endpoints.
• Documentation for the currently selected endpoint.
• Code snippets (available in many different programming languages).
• Example responses and error codes.
Request API Token ↑ Back to top
To connect & test the APIs in a non-production testing environment, please follow the steps below to request for credential setup & API token.
The base URL is: https://uat.api.ext.exxonmobil.com and all API requests must be made over HTTPS with TLS 1.2.
Step 1: Request for an account to call APIs
Submit a request via ‘Support’ form, located in the top right corner of the page, with following info:
- Company Name:
- Business Contact Name / Email:
- IT Contact Name / Email:
Once the account is created, you will be provided the following credentials:
- client_id and client_secret for calling the APIs
Please keep these credentials secured! Do not hard-code them in source code, or store them in the plain text.
Step 2: Get a token
ExxonMobil APIs use OAuth2 Client Credentials Grant Flow to authenticate requests. An access token is required before calling APIs successfully.
To get a token, make a call to https://login.ext.exxonmobil.com/oauth/token and pass your client_id and client_secret assigned to your account.
POST /oauth/token HTTP/1.1
Host: login.ext.exxonmobil.com
Content-Type: application/json
{
“client_id”: “your_account_client_id”,
“client_secret”: “your_account_client_secret”,
“audience”: “https://uat.api.ext.exxonmobil.com”,
“grant_type”: “client_credentials”
}
Your client_id and client_secret for production environment will be different from the test environment. To get a token for production, change the audience to https://api.ext.exxonmobil.com.
You can find access_token in the HTTP response if the call is successfully made. A token will expire after 24 hours by default. When the token expires, repeat the request to /oauth/token endpoint to acquire a fresh new access token.
{
“access_token”: “your_access_token”,
“expire_in”: 86400,
“token_type”: “Bearer”
}
Step 3: Use a token
Now that you’ve acquired a token, use the token to make requests to the resource by passing through Authorization header using Bearer scheme.
GET /customer/chem/v1/accounts HTTP/1.1
Host: uat.api.ext.exxonmobil.com
Authorization: Bearer {your_access_token}
Content-Type: application/json
{
“data”: {...}
}
Status codes
The following status codes are returned by the API.
Status Code |
Description |
200 OK / 201 Created |
Request successful |
400 Bad Request |
Problem with the request |
401 Unauthorized |
Valid access token is not specified |
403 Forbidden |
Not authorized to access the resource |
404 Not Found |
The requested resource does not exist |
500 Internal Server Error |
Error on the internal server |
Our Featured APIs
-
Customer API
-
Storage & Handling API
-
Supplier API