Skip to main content

Account Opening API

  • Updated

    Table of Contents

    Overview

    The MANTL Account Opening API is designed to gives our customers & their partners programmatic access to MANTL application creation and account opening functionality. 

    The MANTL Account Opening API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and methods.

    The MANTL API can be used in UAT environments lower environments, which doesn’t affect your live data or interact with any production resources. 

    Open API specifications are available in Swagger UI here:

    Test requests can be made directly using Swagger UI, or if you prefer to use Postman, the JSON or YAML links can be used to import the specification into Postman.

     

    Authenticating & Calling the API

    The MANTL Account Opening API uses API keys to authenticate requests. You can view and manage your API keys in the MANTL Console under the API Module. 

    Note: Viewing and managing API keys requires appropriate permission.

    An API key is provided on a request via the Authorization header. The API key must be provided as the entire header value, no prefix is accepted e.g. Basic or Bearer.

    Your API keys carry many privileges, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas such as email, Slack, GitHub, client-side code, and so forth.

    Individual API keys can be configured to authorize against different resource requirements. Consult the OpenAPI specification to determine which resources are required for a given operation. As a best practice, an API key should be provisioned with the minimum resources required.

    All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail, including utility operations.

     

    Idempotency

    The MANTL Account Opening API supports idempotency for safely retrying requests without accidentally performing the same operation twice. When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice.

    To perform an idempotent request, provide the optional Idempotency-Key header on the request. All PATCH, POST, and PUT methods support idempotency, however, other methods will return an error. GET and DELETE requests are idempotent by definition.

    MANTL’s idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeds or fails. Subsequent requests with the same key return the same result, including 500 errors.

    A client generates an idempotency key, which is a unique string the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, we allow alphanumeric as well as dash (-), plus (+), forward slash (/), and equals (=) characters. This allows a client to use pseudo-random UUID/GUID or the hash digests hex, base64, and base64url. Idempotency keys are up to 255 characters long and should contain enough entropy to avoid collisions.

    Idempotency keys are cached for 48 hours. If a client makes duplicate requests more than two days apart, the operation may be performed twice. The idempotency layer compares incoming parameters to those of the original request and errors if they don’t match to prevent accidental misuse.

    MANTL returns the status code and response body of the original request only if the original request has been completed before any subsequent requests are received. In the case of parallel requests, the original request will process normally while other in-flight requests will return a 409 Conflict error immediately.

    To identify a previously executed response that’s being replayed from the server, look for the header Original-Request-Id.

     

    API Console Permissions

    If the API Module is enabled in the MANTL Console, FI employees can be granted any of the 3 following permissions:

    1. Ability to view API keys - grants the user the ability to view all API keys associated with the FI
    2. Ability to create and expire API keys - grants the user the create and expire any API key associated with the FI
    3. Ability to view full request and response payloads - grants the user the ability to view full request and response payloads. 

     

    Error handling

    MANTL uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an invalid product ID was provided, etc.). Codes in the 5xx range indicate an error with MANTL’s servers.

    Any client error returned from the MANTL API will include an error code that briefly explains the error reported. If you need further explanation on error handling or specific errors, please reach out to MANTL support and include the request ID.