logo
Documentation Powered by ReDoc

Apto Mobile API (1.0)

E-mail: hello@aptopayments.com Terms of Service

Welcome to the Apto Mobile (B2C) API Reference.

The Apto platform provides a set of APIs designed for the following integration scenarios:

The Mobile API is intended for a final user application which interacts with the Apto platform (B2C). For example, native mobile applications (iOS, Android) or websites.

Note: If you would like to perform a backend integration with the Apto platform, see the Apto Core API (B2B) docs.

Apto Mobile API Overview

The Apto Mobile API is a REST API that uses:

  • HTTP verbs and unique URI's to access the various endpoints.
  • HTTP response codes to indicate statuses and errors.
  • Standard JSON format for all responses.

Note: HTTP is not supported. The Apto Mobile API is served over HTTPS to ensure data privacy.

All API endpoints require:

  • A Mobile API Key. To retrieve your Mobile API Key, register for an account or login into the Apto Developer Portal. Your Mobile API Key is listed on the Developers page.

    Note: In order to register or login to your Apto Developer Portal account, you will need to download a 2FA app such as the Google Authenticator App for your mobile device.

  • Authorization using the Mobile API Key as the Api-Key value. Note: If your authorization is not working, try submitting the Api-Key as Bearer MOBILE_API_KEY replacing MOBILE_API_KEY with the Mobile API key from your account.

    Note: The Apto Mobile API has a request rate limit of 1 request per 30 seconds for the verification and login endpoints.

We’ve tried to make this documentation as straightforward as possible, providing clear code examples, but please contact us with any questions you may have.

Configuration

Use this endpoint to verify your account configuration, and to see which types of user verifications are required.

Provides information about an account configuration.

get/v1/config
/v1/config

This endpoint returns the user verifications required for login and user creation.

Responses

200

successful operation

400

Invalid request

404

No existing account

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "project":
    {
    • "birthdate": "1965-10-20",
    • "primary_auth_credential": "string",
    • "secondary_auth_credential": "string"
    }
}

Verifications

Use these endpoints to verify a user and retrieve a user token. A user token is required to login and access API resources.

Starts a verification of a phone number or email address.

post/v1/verifications/start
/v1/verifications/start

This endpoint starts a verification of a phone number or email address, and returns the verification ID and status.

Request Body schema: application/json
One of
  • VerificationPhoneDataPoint
  • VerificationEmailDataPoint
datapoint_type
required
string
Value: "phone"
datapoint
required
object

Responses

200

successful operation

400

Invalid request

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "datapoint_type": "phone",
  • "datapoint":
    {
    • "data_type": "phone",
    • "country_code": "1",
    • "phone": "5551230000"
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "verification",
  • "verification_type": "phone",
  • "verification_mechanism": "phone",
  • "verification_id": "entity_XXXXXXXXXXXXXXXXX",
  • "status": "pending",
  • "secondary_credential":
    {
    • "type": "verification",
    • "verification_type": "birthdate",
    • "verification_id": "entity_XXXXXXXXXXXXXXXXX",
    • "status": "pending"
    }
}

Starts a verification of the primary credential.

post/v1/verifications/primary/start
/v1/verifications/primary/start

This endpoint starts a verification of the primary credential and returns the verification ID and status.

Responses

200

successful operation

400

Invalid request

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "verification",
  • "verification_type": "phone",
  • "verification_mechanism": "phone",
  • "verification_id": "entity_XXXXXXXXXXXXXXXXX",
  • "status": "pending",
  • "secondary_credential":
    {
    • "type": "verification",
    • "verification_type": "birthdate",
    • "verification_id": "entity_XXXXXXXXXXXXXXXXX",
    • "status": "pending"
    }
}

Finish a verification of a phone number, email address, or date of birth.

post/v1/verifications/{verification_id}/finish
/v1/verifications/{verification_id}/finish

This endpoint completes a verification of a phone number, email address, or date of birth, and returns the verification ID and status. The secret value for a phone number or email verification is the 6-digit number sent to the specified phone number or email. If verifying a date of birth, the secret value is the user's date of birth in YYYY-MM-DD format.

path Parameters
verification_id
required
string <entity_[0-9af]{16}>

ID of verification

Request Body schema: application/json
secret
required
string

Responses

200

successful operation

400

Invalid request

404

No existing verification

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "secret": "123456"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "verification",
  • "verification_type": "phone",
  • "verification_mechanism": "phone",
  • "verification_id": "entity_XXXXXXXXXXXXXXXXX",
  • "status": "pending",
  • "secondary_credential":
    {
    • "type": "verification",
    • "verification_type": "birthdate",
    • "verification_id": "entity_XXXXXXXXXXXXXXXXX",
    • "status": "pending"
    }
}

Restarts the verification of a phone number or email address.

post/v1/verifications/{verification_id}/restart
/v1/verifications/{verification_id}/restart

This endpoint restarts a verification, and returns a new verification ID and status. This endpoint can be used in place of the Start Verification endpoint, once the verification flow has started. Note: This endpoint can only be used for phone number or email address verification.

path Parameters
verification_id
required
string <entity_[0-9af]{16}>

ID of verification

Responses

200

successful operation

400

Invalid request

404

No existing verification

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "verification",
  • "verification_type": "phone",
  • "verification_mechanism": "phone",
  • "verification_id": "entity_XXXXXXXXXXXXXXXXX",
  • "status": "pending",
  • "secondary_credential":
    {
    • "type": "verification",
    • "verification_type": "birthdate",
    • "verification_id": "entity_XXXXXXXXXXXXXXXXX",
    • "status": "pending"
    }
}

Retrieves a verification

get/v1/verifications/{verification_id}/status
/v1/verifications/{verification_id}/status

Retrieves a verification returning its ID and status

path Parameters
verification_id
required
string <entity_[0-9af]{16}>

ID of verification

Responses

200

successful operation

400

Invalid request

404

No existing verification

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "verification",
  • "verification_type": "phone",
  • "verification_mechanism": "phone",
  • "verification_id": "entity_XXXXXXXXXXXXXXXXX",
  • "status": "pending",
  • "secondary_credential":
    {
    • "type": "verification",
    • "verification_type": "birthdate",
    • "verification_id": "entity_XXXXXXXXXXXXXXXXX",
    • "status": "pending"
    }
}

Users

Use these endpoints to manage users and user data.

Creates a user

post/v1/user
/v1/user

Creates a user and its initial data

Request Body schema: application/json
metadata
string

You can use this parameter to store a string up to 256 characters with the user.

data_points
required
object

Responses

200

successful operation

400

Invalid request

401

User session expired when trying to create a user with the same data more then once

404

No existing verification

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "metadata": "string",
  • "data_points":
    {
    • "type": "list",
    • "data":
      [
      • {
        }
      ]
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "user",
  • "user_id": "crdhldr_b04f29605a018f7d72a2",
  • "user_token": "E5PWX4T9dcPriIo ... ao0QZLC6YL/dAyaA8",
  • "user_data":
    {
    • "type": "list",
    • "data":
      [
      • {
        }
      ],
    • "page": 0,
    • "rows": 5,
    • "has_more": true,
    • "total_rows": 10
    },
  • "metadata": "string"
}

Updates a user

put/v1/user
/v1/user

Updates a user data

Request Body schema: application/json
data_points
required
object

Responses

200

successful operation

400

Invalid request

404

User does not exist

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "data_points":
    {
    • "type": "list",
    • "data":
      [
      • {
        }
      ]
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "user",
  • "user_id": "crdhldr_b04f29605a018f7d72a2",
  • "user_token": "E5PWX4T9dcPriIo ... ao0QZLC6YL/dAyaA8",
  • "user_data":
    {
    • "type": "list",
    • "data":
      [
      • {
        }
      ],
    • "page": 0,
    • "rows": 5,
    • "has_more": true,
    • "total_rows": 10
    },
  • "metadata": "string"
}

Retrieves a user

get/v1/user
/v1/user

Retrieves a user and its data

Responses

200

successful operation

400

Invalid request

404

User does not exist

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "user",
  • "user_id": "crdhldr_b04f29605a018f7d72a2",
  • "user_token": "E5PWX4T9dcPriIo ... ao0QZLC6YL/dAyaA8",
  • "user_data":
    {
    • "type": "list",
    • "data":
      [
      • {
        }
      ],
    • "page": 0,
    • "rows": 5,
    • "has_more": true,
    • "total_rows": 10
    },
  • "metadata": "string"
}

User login

post/v1/user/login
/v1/user/login

Login user into the system and returns its ID and access token

Request Body schema: application/json
verifications
required
object

Responses

200

successful operation

400

Invalid request

Request samples