Get Started

Welcome to USCIS API Platform.

Introduction

Welcome to the Torch API Program! Our APIs offer the following benefits:

Get started right away: Visit our Developer Portal to find out what our APIs do, how they work and what you need to do to interface with them. Use our sandbox and get building now. Our APIs need just a few lines of code to run in your applications.
Clear overview: You always know what is happening. Use our API analytics to track your users’ activity in your applications and adjust your tactics if necessary.
Be creative: We are giving you the opportunity to use exclusive APIs to help shape the future of USCIS API Services.

Our API Consumer Onboarding Experience covers the step-by-step process, guiding you from Account Creation to Production Access

Onboarding Steps

Step One: Build Your App

Get started by signing up for an account. Already a user? Login here.

Add your Developer App on the Account page and request access to the APIs*. Your Developer App Client Credentials will grant access to the sandbox environments for you to send test data. Refer to API specific documentation to learn how to structure your payload, as you build your API solution.

_{*Some APIs are not available for production access and are available for feedback purposes only. APIs flagged as Sandbox Only are not available for production access at this time.}

Step Two: Schedule your Demo

Email us when you are ready to demo your app to upgrade from sandbox to production. We require a signed affidavit to move forward.

Step Three: Demo your App

Prepare for your app demonstration. Showcase what you have built with our APIs based on the criteria we’ll email you.

Step Four: Go Live

Pass the app demo and receive production keys to expose your API solution to the public.

Build Your App: Build a Developer App with access to Sandbox

Explore API Products

Want to be inspired and learn what you could build? Our available APIs are displayed on the API Products page. From here you can navigate to the API overview pages for details of a specific API. Review the technical documentation and when you are ready to test the APIs, create your Developer App in the portal.

Creating a Developer App

Creating the Developer App is the first step to gaining access to the APIs in the sandbox environment. Your Developer App will grant Client Credentials used to secure an Access Token via OAuth. The Access Token is then verified to access Sandbox Data. Pay close attention to APIs listed as Sandbox Only, as they are available for feedback purposes at this time.

For guidance refer to the How do I Create an App documentation.

Authentication

API authentication is done with Access Tokens. To obtain an Access Token, you need to call our OAuth URL and provide your Client Credentials. Torch APIs are secured with OAuth 2.0 Authentication Policy, however alternative mechanism can vary per API depending on required level of authentication.

Environments

Sandbox: https://api-int.uscis.gov/oauth/accesstoken

Production: Currently Unavailable

OAuth Flows

We use the following three flows for getting an access token:

Client credentials,
Authorization Code Flow
Refresh Token

The following support documentation can help you locate and utilize your Torch API Client Credentials:

Client Credentials are enabled for development and can be referenced as you build in your preferred programming language. You can reference the technical documentation located on our API Products Page.

NOTE: To move forward with production access, we will require you send API traffic using mock dynamic data. The API Documentation will guide you on how to structure your payloads.

Error Handling

This section provides an overview of USCIS APIs error model.

Error Format

All USCIS APIs throw errors in following JSON format:

{
	"errors": [
		{
			"code": "ERROR_UNIQUE_CODE",    
			"message": "ERROR_MESSAGE",
			"category" : "SHORT_DESCRIPTION/ERROR_CATEGORY",
			"reference" : "API_DOCUMENTATION_LINK",
			"status" : "HTTP_STATUS_CODE",
			"traceId" : "UUID"
			
		}
	]

}

Please email us at [email protected] for any questions throughout your build!

Schedule Your Demo: Requesting Production Access

Prerequisites to Scheduling your Demo

Your Team	Torch API
Build an API solution up to a staging environment, ready for production Send API traffic to sandbox environment containing dynamic data Sign and complete the provided affidavit Review demo criteria for APIs, and prepare for demo	Validate the API traffic is sending sufficient dynamic data. Send the affidavit and secure a signature from your team. Provide demo criteria specific to API’s for which you are requesting production access.

Path to Production

We will require you demo your app after successfully building your API solution.
It is required your product has completed sufficient testing and is in a staging environment ready for production deployment.

Start the Demo Process

To start the demo process email us at [email protected].

We will review your request and validate the HTTPS Request sent from your Developer App. We will send an Attestation when we have confirmed you have met the minimum requirements to begin the demo process.

Sign and Complete the Affidavit

We will validate the API traffic is sufficient and promote you to the next step by emailing you an affidavit.

Return the completed and signed affidavit to [email protected]

Book your App Demo Appointment

We will provide a scheduling link after we have reviewed your signed affidavit. Demos are available on a first-come, first-served basis every Tuesday and Wednesday afternoon.

Demo Your App: Preparing for your App Demo

Prepare for your Demo

Your development team must be available during the session to conduct the demonstration and answer any questions.
You must provide a complete (from start to finish) demonstration of your application. Your demonstration must cover the following scenarios that display how your application is using the APIs.

During your demonstration session, we will rate the following with either Pass or Fail:

Whether a user can easily enter the required information in your application throughout the user interface
Whether a user was able to successfully upload an encoded file as outlined in the documentation.
Whether the user’s completed application successfully converts to a JSON payload.
Whether the application successfully authenticated to our API using OAuth 2.0
Whether the USCIS API HTTPS response was successfully sent back and presented in the application
Whether your application tracks case status from your application

Demo Requirements and Etiquette

This is your time to shine and show us what you have built. Provided below are the demo requirements and etiquette to ensure a positive demo experience:

Be ready to share your screen and display the product.
Developer tools or other applications are recommended to share if they successfully illustrate API transmission.
We will record your session.
Audio is required, camera is optional.
Microsoft Teams will host the App Demo. Please ensure you download before your demo.
Questions and usability feedback will be reserved for the end of your demo.

Go Live: Granting Production Keys

Once you have completed your demonstration, we will review the data and session results to ensure that your application has accurately passed through the APIs. We will notify you of your session results and any additional information by email.

Production access and instructions will be granted when you have successfully passed your App Demo.

Support

Questions or problems? We are happy to help. Please check our FAQ page for the answers to frequently asked questions.

Need Additional Documentation? Check out our Articles for Helper Documentation related to the Torch Developer Portal and API Products!

Can’t find the answer you need? Email us at [email protected]