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:
- How to get Access Token with Client Credentials
- How to test an API in Sandbox using the“Try It” Authorize Feature
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 |
|
|
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]
Confirm App Demo Appointment
We will provide available dates after confirmation of your signed affidavit. Demos are available on a first come, first serve, basis on Tuesdays, Wednesdays and Fridays at 1:00PM EST and 2:30 PM EST. We will allot up to 60 minutes for your demonstration session.
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]