User Intent Metadata

The User Intent creation resource allows for an optional metadata object to be submitted within the request payload.

🚧
Do not submit any sensitive information (bank account numbers, card details, PII, etc.) as metadata keys or values.

Up to 25 key/value pairs can be specified within the metadata object.

Keys must be of type string and 1–64 characters in length (allowed character set: [a-zA-Z0-9_.-]).

Values must be of type string and 1–256 characters in length (uniqueness not required).

If the metdata object is specified, it will be returned with the following:

Webhooks:
- user_intent_updated
  - https://docs.astra.finance/reference/user-webhooks#user-intent-updated
- user_updated
  - https://docs.astra.finance/reference/user-webhooks#user-updated
API
- https://docs.astra.finance/reference/get_v1-user-intent-id
- https://docs.astra.finance/reference/get_v1-user

Recommended Uses

The creation of a User Intent is the first step for onboarding a personal User in Astra.

To track your customers as they onboard in Astra, you could submit a unique identifier tied to that customer in your system.

Example:

Passing an internal_customer_id key with a UUID identifier value where the unique identifier in your system 7797f3bc-35d0-416d-a5af-99e25b4ad02c corresponds to an individual named John Smith.

curl --request POST \
     --url https://api-sandbox.astra.finance/v1/user_intent \
     --header 'accept: application/json' \
     --header 'authorization: Basic MTIzOjEyMw==' \
     --header 'content-type: application/json' \
     --data '
{
  "first_name": "John",
  "last_name": "Smith",
  "date_of_birth": "1985-02-03",
  "ssn": "1234",
  "phone": "INDIVIDUAL_PHONE",
  "email": "INDIVIDUAL_EMAIL",
  "address1": "123 Astra Ave",
  "city": "Palo Alto",
  "state": "CA",
  "postal_code": "94304",
  "ip_address": "192.0.2.0",
  "metadata": {
    "internal_customer_id": "7797f3bc-35d0-416d-a5af-99e25b4ad02c"
  }
}
'

You will receive a user_intent_updated webhook once the status of the User Intent updates to either approved or rejected.

{
  "webhook_type": "user_intent_updated",
  "webhook_id": "364f57aa-47dd-461b-8df4-d6388fb2d05e",
  "user_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA",
  "resource_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA",
  "metadata": {
    "internal_customer_id": "7797f3bc-35d0-416d-a5af-99e25b4ad02c"
  }
}

Once you successfully onboard the individual (see https://docs.astra.finance/docs/onboarding-personal-users), if you take their access_token and fetch User details, the metadata submitted during User Intent creation persists.

curl --request GET \
     --url https://api-sandbox.astra.finance/v1/user \
     --header 'accept: application/json' \
     --header 'authorization: Bearer abc123'

Response:

{
    "email": "INDIVIDUAL_EMAIL",
    "first_name": "John",
    "id": "526133f6e29a4cdba37064ceae0dc326",
    "kyc_type": "verified",
    "last_name": "Smith",
    "metadata": {
        "internal_customer_id": "7797f3bc-35d0-416d-a5af-99e25b4ad02c"
    },
    "phone": "INDIVIDUAL_PHONE",
    "receive_only": false,
    "rejection_reasons": [],
    "status": "approved",
    "user_type": "personal"
}

In the future, if the User experiences any status updates, you will receive a user_updated webhook.

{
  "webhook_type": "user_updated",
  "webhook_id": "364f57aa-47dd-461b-8df4-d6388fb2d05e",
  "user_id": "526133f6e29a4cdba37064ceae0dc326",
  "resource_id": "526133f6e29a4cdba37064ceae0dc326",
  "metadata": {
    "internal_customer_id": "7797f3bc-35d0-416d-a5af-99e25b4ad02c"
  }
}