> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Add Virtual Card Address
Save a billing address for virtual card issuance on the caller's account. The address is saved as a `BILLING` user address and can later be passed to `createVirtualCard` as `userAddressId`.
When `authUserId` is provided, the address is saved for that authorized user's underlying user while remaining attached to the caller's account. The `authUserId` must be an ACTIVE non-owner authorized user assignment on the caller's account.
If an identical billing address already exists for the target cardholder on the caller's account, the existing address is returned instead of creating a duplicate. Matching is done on address fields, account, target user, and `BILLING` type.
**Prerequisites:** a Bearer token with the `CREATE_VIRTUALCARD` scope.
**The billing address must be verifiable**
This mutation stores the billing address. It must be a real, deliverable **US** address (`US`, `USA`, or `United States`) with a correct city, state, and ZIP, and **PO boxes are not accepted**. The USPS/Smarty check runs when a virtual card is created — an address that can't be verified there causes card creation to fail with `VC-0025`. See [Address Formatting Requirements](/concepts/address-formatting-requirements) for the full field rules and examples.
```graphql theme={null}
mutation AddVirtualCardAddress($input: AddVirtualCardAddressInput!) {
addVirtualCardAddress(input: $input) {
userAddressId
streetAddressLine1
streetAddressLine2
country
city
state
postalCode
}
}
```
## Parameters
| Parameter | Type | Required | Description |
| --------------------------------------- | ------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| input | AddVirtualCardAddressInput! | Yes | Wrapper object for the billing address request. |
| input.billingAddress | VirtualCardBillingAddressInput! | Yes | Billing address to save for virtual card issuance. |
| input.billingAddress.streetAddressLine1 | String! | Yes | Street address. PO boxes are not accepted by the issuer. |
| input.billingAddress.streetAddressLine2 | String | No | Optional apartment, suite, or secondary address line. Empty values are saved as `null`; non-empty values are trimmed. |
| input.billingAddress.country | String! | Yes | Country name. Currently only United States addresses are supported by the card issuer. |
| input.billingAddress.city | String! | Yes | City. Saved in uppercase. |
| input.billingAddress.state | String! | Yes | State name or two-letter US state code. Saved in uppercase. |
| input.billingAddress.postalCode | String! | Yes | 5-digit US ZIP code. Saved in uppercase. |
| input.authUserId | UUID | No | Authorized user ID (UAC role assignment ID). When provided, the address is saved for that authorized cardholder. |
## Response
```json theme={null}
{
"data": {
"addVirtualCardAddress": {
"userAddressId": "1f6b2c3d-4e5f-4a67-9a10-2b3c4d5e6f70",
"streetAddressLine1": "123 Main St",
"streetAddressLine2": "Apt 5",
"country": "United States",
"city": "NEW YORK",
"state": "NY",
"postalCode": "10001"
}
}
}
```
## Response fields
| Field | Type | Description |
| -------------------- | ------ | ------------------------------------------------------------------------------------ |
| `userAddressId` | UUID | Saved billing address ID. Pass this value as `userAddressId` to `createVirtualCard`. |
| `streetAddressLine1` | String | Street address line 1. |
| `streetAddressLine2` | String | Street address line 2, or `null` when not provided. |
| `country` | String | Country name. |
| `city` | String | City saved on the address. |
| `state` | String | State saved on the address. |
| `postalCode` | String | Postal code saved on the address. |
## Example requests
Save a billing address for the caller:
```bash theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"query": "mutation AddVirtualCardAddress($input: AddVirtualCardAddressInput!) { addVirtualCardAddress(input: $input) { userAddressId streetAddressLine1 streetAddressLine2 country city state postalCode } }",
"variables": {
"input": {
"billingAddress": {
"streetAddressLine1": "123 Main St",
"streetAddressLine2": "Apt 5",
"country": "United States",
"city": "New York",
"state": "NY",
"postalCode": "10001"
}
}
}
}'
```
Save a billing address for an authorized user:
```bash cURL theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"query": "mutation AddVirtualCardAddress($input: AddVirtualCardAddressInput!) { addVirtualCardAddress(input: $input) { userAddressId streetAddressLine1 streetAddressLine2 country city state postalCode } }",
"variables": {
"input": {
"authUserId": "8b2c1e0a-7d4f-4a9b-9c2d-1f3e4a5b6c7d",
"billingAddress": {
"streetAddressLine1": "456 Market St",
"streetAddressLine2": "Suite 200",
"country": "United States",
"city": "San Francisco",
"state": "CA",
"postalCode": "94105"
}
}
}
}'
```
```typescript TypeScript theme={null}
const response = await fetch('https://transactional-graph.staging.fluzapp.com/api/v1/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${accessToken}`,
},
body: JSON.stringify({
query: `
mutation AddVirtualCardAddress(
$input: AddVirtualCardAddressInput!
) {
addVirtualCardAddress(input: $input) {
userAddressId
streetAddressLine1
streetAddressLine2
country
city
state
postalCode
}
}
`,
variables: {
input: {
authUserId: '8b2c1e0a-7d4f-4a9b-9c2d-1f3e4a5b6c7d',
billingAddress: {
streetAddressLine1: '456 Market St',
streetAddressLine2: 'Suite 200',
country: 'United States',
city: 'San Francisco',
state: 'CA',
postalCode: '94105',
},
},
},
}),
});
const data = await response.json();
console.log('Virtual card address saved:', data.data.addVirtualCardAddress);
```
## Error codes
| Code | Message | Description |
| ----------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `ARG-0001` | Invalid arguments received | A required address field is missing, a value is empty, or `authUserId` is not a valid UUID. |
| `AUTH-0008` | Invalid user access | The Bearer token could not be resolved to a caller. Verify the token is valid. |
| `AUTH-0031` | The requested scopes must be granted by the user first. | The token is missing the `CREATE_VIRTUALCARD` scope required to save virtual card addresses. |
| `AUTH-0034` | No authorized user found with this id on the caller's account. | The `authUserId` does not exist on the caller's account, is not ACTIVE, or refers to an OWNER assignment. |
| `VC-0001` | Please try another payment method. If you continue experiencing issues, please contact our support team. | A general failure occurred while saving the billing address. Please retry or contact support. |
## Next steps
Pass the returned `userAddressId` into `createVirtualCard`.
Required before the card can be used for in-person or PIN-prompted transactions.