# Quickstart - V1 This guide describes how to get started with the Card Attributes Service API. It is designed for an integration developer as the first step in learning how to integrate with the API, but should be simple enough for anyone to follow. ## Using the API For this quickstart you will need the following. * Admin access to the VGS Dashboard and a VGS sandbox or live vault. * Access to a terminal command line. Once you are ready for full integration, the full Open API specification for this API is located [here](/cmp/developer-resources/api/credential-management-v1-apis-calm/card-attributes-v1.md) in our API Reference store. ## Create and store your API credentials This API authenticates using the OAuth2.0 client credentials flow, which requires a client id and secret to obtain an access token. You can create credentials in your VGS dashboard or via the VGS CLI, following these instructions. {% stepper %} {% step %} ### Create a service account To create a service account for your organization, go to the Service Accounts section of the *VGS Dashboard > Organization settings* page and click the "Create New" button. Assign a name for this credential and select scopes. Scopes indicate the services you wish to be accessed by these credentials. If they are available, assign one of the two following scopes: `card-attributes:basic` for basic level access to the attributes or `card-attributes:advanced` for advanced access. Advanced has more capabilities than basic; the differences are outlined below. If you do not have access to these scopes, you can create a service account without adding these scopes; you will still have access to the basic version of the API, but will be limited to 15 times a day. {% endstep %} {% step %} ### Save your Client ID and Secret Important! Be sure to save your Client ID and Secret!! You will not see the client secret again after it is presented to you on the screen. {% endstep %} {% step %} ### Store credentials as environment variables Store your credentials in environment variables on your device by going into a terminal and entering these commands. Replace `` and `` with your actual Client Id and Secret. {% code title="Set VGS credentials (bash)" %} ```bash export VGS_CLIENT_ID= export VGS_CLIENT_SECRET= ``` {% endcode %} {% endstep %} {% endstepper %} ## Try out the API Now that you have stored the environment variables on your device, the following cURL command will retrieve an access token and use that token to call the VGS Card Attributes API. {% stepper %} {% step %} ### Retrieve an access token and call the Attributes endpoint {% code title="cURL example" %} ```bash curl https://card-enrichment-api.live.verygoodvault.com/attributes -H "Authorization: Bearer $( curl --request POST \ --url 'https://auth.verygoodsecurity.com/auth/realms/vgs/protocol/openid-connect/token' \ --header 'content-type: application/x-www-form-urlencoded' \ --data grant_type=client_credentials \ --data client_id=${VGS_CLIENT_ID} \ --data client_secret=${VGS_CLIENT_SECRET} | jq -r .access_token)" \ -H 'Content-Type: application/json' \ -d '{ "number": "411111" }' -v ``` {% endcode %} {% endstep %} {% endstepper %} ## Response Body The command will return a JSON object similar to the one below. {% code title="Sample response" %} ```javascript { "bin": "411111", "brand": "VISA", "issuing_organization": "CONOTOXIA SP. Z O.O", "card_type": "DEBIT", "card_category": "CLASSIC", "issuing_country_name": "POLAND", "issuing_country_code": "616", "maximum_pan_length": 16, "card_commercial_type": "PERSONAL", "regulation_status": "UNREGULATED", "version": "v20241206", "prepaid_type": "NONRELOADABLE" } ``` {% endcode %} ## Additional Test data Replace the `411111` in the above REST API with the samples below. * 223009 : Mastercard * 340002 : American Express ## Attribute Summary | Attribute | Definition | Access Level Required | | ---------------------- | ------------------------------------------------------------------------------- | --------------------- | | bin | bin number | Basic | | brand | The card brand facilitates payment transactions. Eg: Visa, Mastercard, Discover | Basic | | issuing\_organization | The bank that issued the card to the customer. Eg: Chase, Bofa, USBank | Basic | | card\_type | The type of card that is issued by the issuing bank. Eg: Credit , Debit | Basic | | card\_category | Category of Card. Eg: BUSINESS , PREPAID | Basic | | issuing\_country\_name | ISO country name that is associated with an ISO code. Eg: USA, United Kingdom | Basic | | issuing\_country\_code | Issuing country ISO number: Eg 840 for USA | Basic | | maximum\_pan\_length | maximum PAN length | Basic | | card\_commercial\_type | Defines if the BIN is PERSONAL or COMMERCIAL | Basic | | regulation\_status | Defines if the BIN is regulated or non-regulated | Basic | | version | Date at which the returned data was last updated | Basic | | prepaid\_type | Indicates if the card is a prepaid debit card | Advanced | | cobadged\_brands | Lists the network co-badges of the card, if applicable | Advanced | With the Advanced scope assigned, all basic attributes are returned as well as advanced attributes. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.verygoodsecurity.com/cmp/developer-resources/api/credential-management-v1-apis-calm/card-attributes-v1/quickstart-v1.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.