API Reference

API Overview

The UNS API provide different sets of endpoints that enable you to interact with the resources within the API.

🚧

API KEYS

You need API keys to access the API.

UNS API

Detailed documentation for UNS API endpoints is at the UNS API Documentation

Setup

Before you begin, set the following variables to your Postman environment:

  • connection_url -> URL String to connect to UNS API
  • auth_connection_url -> URL String to connect to the auth service from UNS API in order to have access to all resources linked to UNS-users.
  • org_code -> Your Organization code identifier issued by UNS in order to use the API
  • api_key -> Your Organization Secret issued by UNS in order to use the API
  • client_id -> Your Client Identiefier from your UNS-OAuth Application
  • secret_key ->Your Client Secret Identiefier from your UNS-OAuth Application

Once these parametrers are set, your are ready to use UNS API through this Postman collection.

For UNS in order to enchance our services to our developers by providing future features and insights around /names. We encourage you to provide in each request the following headers:

  • X_CLIENT_IP -> Device IP of the user when interacting with your feature built on top of UNS-API, using the following format:

    X_CLIENT_IP: 78.153.154.81

  • X_CLIENT_COORDINATES -> Device geolocation of the user when interacting with your feature built on top of UNS-API, using the follwoing format: ,

    X_CLIENT_COORDINATES: -1.456,34.923

Pagination

UNS API Paginated endpoints allow for both cursor and apge based paginations schemas.

All IDs from UNS API resources are Sorteable identifiers by default.

Page based

Parameters are passsed as url_params similar to the follow example:

{{connection_url}}/v1/personas/{{persona_id}}/names?page=page&page_size=page_size

Both parameteres are Integers, page_size has a limit of 250 results per request.

Cursor based

Parameters are passsed as url_params similar to the follow example:

{{connection_url}}/v1/personas/{{persona_id}}/names?cursor=resource_id&limit=limit

cursor is the resource_id from the resource to start pulling results. limit has a limit of 250 results per request.

Authentication

All request to UNS API must need to have both org_code and api_key parameters in the headers of the request. Additionally all UNS API Endpoints which require access to user related resources, personas, locks, names (partially), auth(partially), resolver must add the additional header with the user access_token.

"x-org-code": {{org_code}}

"x-api-key": {{api_key}}

"Authorization": Bearer {{access_token}}

Errors

UNS API provides two levels of of error information in order to properly handle any possible situation when integrating UNS services into your application or service.

Error Types

Error types are used to provide a generic error descriptor which is matches the status code returned by UNS API.

  • API_ERROR (STATUS CODE: 500)
  • INVALID_REQUEST_ERROR (STATUS CODE: 400)
  • NOT_FOUND (STATUS CODE: 404)
  • CONFLICT(STATUS CODE: 409)
  • AUTHENTICATION_ERROR (STATUS CODE: 401)
  • METHOD_NOT_ALLOWED (STATUS CODE: 405)
  • FORBIDDEN (STATUS CODE: 403)

Error Codes

Error codes are used to provide a fine grain detail of the error if possible. Each code has a unique id identifying each unmet condition when interacting with UNS API.

Generic Error codes

{"code": "THE_REQUESTED_URL_WAS_NOT_FOUND_ON_THE_SERVER", "num_code": 60000}
{"code": "METHOD_NOT_ALLOWED", "num_code": 60001}
{"code": "MISSING_AUTHORIZATION", "num_code": 60002}
{"code": "FORBIDDEN", "num_code": 60003}
{"code": "BAD_REQUEST", "num_code": 60004}
{"code": "REQUEST_VALIDATION_ERROR", "num_code": 60005}
{"code": "RESOURCE_NOT_FOUND", "num_code": 60006}
"code": "CONFLICT_WITH_TARGET_RESOURCE", "num_code": 60007}
{"code": "EXCEEDED_CONTENT_LENGTH_OF_REQUEST", "num_code": 60008}
# Names errors
{"code": "NAME_ALREADY_TAKEN", "num_code": 60100}
{"code": "NAME_TOO_SHORT", "num_code": 60101}
{"code": "NAME_TOO_LONG", "num_code": 60102}
{"code": "NAME_BAD_FORMAT", "num_code": 60103}
{"code": "UUID_BAD_FORMAT", "num_code": 60104}
{"code": "TRADEMARKED", "num_code": 60105}
{"code": "NAME_DOES_NOT_BELONG_TO_PERSONA", "num_code": 60106}
{"code": "NAME_NOT_FOUND", "num_code": 60107}
{"code": "BLOCKCHAIN_NOT_SUPPORTED", "num_code": 60108}
{"code": "NAME_RESERVED", "num_code": 60109}
{"code": "NAME_NOT_ALLOWED", "num_code": 60110}
{"code": "NAME_PREMIUM", "num_code": 60111}
# Payment errors
{"code": "PAYMENT_ATTEMPTED_FOR_UNLOCKED_NAME", "num_code": 60200}
{"code": "STRIPE_UNEXPECTED_RESPONSE", "num_code": 60201}
{"code": "STRIPE_INVALID_SIGNATURE", "num_code": 60202}
{"code": "STRIPE_INVALID_PAYLOAD", "num_code": 60203}
{"code": "STRIPE_UNABLE_TO_CREATE_PRODUCT", "num_code": 60204}
{"code": "BAD_URL_FORMAT", "num_code": 60205}
{"code": "NAME_ALREADY_PAID", "num_code": 60206}
# Organizations errors
{"code": "ORGANIZATION_CODE_ALREADY_EXISTS", "num_code": 60300}
{"code": "PUBLIC_KEY_INVALID", "num_code": 60301}
# Personas errors
{"code": "PERSONA_MISSING_REQUIRED_FIELDS", "num_code": 60400}
{"code": "PHONE_BAD_FORMAT", "num_code": 60401}
{"code": "EMAIL_BAD_FORMAT", "num_code": 60402}
{"code": "PHONE_EMAIL_NOT_MATCH", "num_code": 60403}
{"code": "PERSONA_NOT_FREE_NAMES_REMAINING", "num_code": 60404}
{"code": "PERSONA_NOT_FOUND", "num_code": 60405}
# Resolver Fields errors
{"code": "RESOLVER_FIELD_NOT_ALLOWED", "num_code": 60501}
{"code": "RESOLVER_FIELD_NOT_ALLOWED", "num_code": 60502}
{"code": "TOKEN_RESOLVER_FIELD_NOT_MUTABLE", "num_code": 60503}
{"code": "RESOLVER_SCOPE_NOT_ALLOWED", "num_code": 60504}
{"code": "RESOLVER_SCOPE_NOT_FOUND", "num_code": 60505}
{"code": "ADDRESS_VALIDATION_FAILED", "num_code": 60506}
{"code": "FIELD_MISSING_REQUIRED_FIELDS", "num_code": 60507}
# Social Connections errors
{"code": "VERIFICATION_ID_NOT_VALID", "num_code": 60601}
{"code": "SOCIAL_CONNECTION_NOT_SUPPORTED", "num_code": 60602}
{"code": "VERIFICATION_FIELD_NOT_VALID", "num_code": 60603}
{"code": "INVALID_VERIFICATION", "num_code": 60604}
{"code": "SOCIAL_CONNECTION_NOT_FOUND", "num_code": 60605}
{"code": "VERIFICATION_RESOURCE_NOT_FOUND", "num_code": 60606}
{"code": "DUPLICATED_SOCIAL_CONNECTION", "num_code": 60607}
# Tokens errors
{"code": "NAME_ALREADY_TOKENIZED", "num_code": 60701}
# Misc. errors
{"code": "NAME_LOCKED_BY_DIFFERENT_PERSONA", "num_code": 70101}
{"code": "PRICE_DIFFERENT_FROM_NAME_MODEL", "num_code": 70102}
{"code": "NAME_NOT_AVAILABLE_TO_ASSIGN", "num_code": 70103}

API FAQs

Can I contact UNS about the API?
Yes. You can reach out to support at [email protected]