Knowledge Center

Knowledge Center > API > REST API > REST API Reference > Accounts > Get account

Get account

This REST API reference describes how to retrieve basic information about a customer account.

This REST call is a quick retrieval that doesn't include the account's subscriptions, invoices, payments, or usage details. Use the Get account summary to get more detailed information about an account.

Request

  • Production: GET https://api.zuora.com/rest/v1/accounts/{account-key}
  • API Sandbox: GET https://apisandbox-api.zuora.com/rest/v1/accounts/{account-key}

Request parameters

account-key required path Account number or account ID

Response

success

Contains true if successful, otherwise false.

processId

Internal process ID to assist Zuora support. Only returned if success is false.

reasons

Information on one or more reasons for the result. Only returned if success is false.

code

Eight-digit numeric error code

message

Description of the error

basicInfo

Container for basic information about the account:

id

Account ID

name

Account name

accountNumber

Account number

notes

Notes associated with the account, up to 65,535 characters

status

Account status; possible values are: Active, Draft, Canceled.

crmId

CRM account ID for the account, 100 characters or less

invoiceTemplateId

A template ID configured in Z-Billing settings

communicationProfileId

ID of a communication profile

cf_txtn__c

One or more optional custom fields

cf_pkn__c

One or more optional custom fields

billingAndPayment

Container for billing and payment information for the account: 

billCycleDay

Billing cycle day (BCD), the day of the month when a bill run generates invoices for the account

currency

A currency defined in the administrative web-based UI

paymentTerm

A payment-terms indicator defined in the web-based UI administrative settings, e.g., "Net 30"

paymentGateway

The name of the payment gateway instance. If null or left unassigned, the Account will use the Default Gateway.

metrics

Container for account metrics:

balance

The customer's total invoice balance minus credit balance

totalInvoiceBalance

Total of all open invoices

creditBalance

Current credit balance

contractedMrr

Future expected MRR that accounts for future upgrades, downgrades, upsells and cancellations

billToContact

Container for bill-to contact information:

address1

First address line, 255 characters or less

address2

Second address line, 255 characters or less

city

City, 40 characters or less

country

Country name or abbreviation

county

County; 32 characters or less. Z-Tax uses this information to calculate county taxation.

fax

Fax phone number, 40 characters or less

firstName

First name, 100 characters or less

homePhone

Home phone number, 40 characters or less

lastName

Last name, 100 characters or less

mobilePhone

Mobile phone number, 40 characters or less

nickname

NIckname for this contact

otherPhone

Other phone number, 40 characters or less

otherPhoneType

Possible values are: Work, Mobile, Home, Other.

personalEmail

Personal email address, 80 characters or less

zipCode

Zip code, 20 characters or less

state

State name or 2-character abbreviation

taxRegion

A region string, defined in your Z-Tax tax rules

workEmail

Work email address, 80 characters or less

workPhone

Work phone number, 40 characters or less

cf_txtn__c

One or more optional custom fields

cf_pkn__c

One or more optional custom fields

soldToContact

Container for sold-to contact information.  Uses the same field structure as billToContact.

batch

optional

The alias name given to a batch. A string of 50 characters or less.

taxInfo

optional

Container for tax exempt information, used to establish the tax exempt status of a customer account.

companyCode

 

Unique code that identifies a company account in Avalara.

exemptCertificateId

ID of the customer tax exemption certificate. 

exemptCertificateType

Type of tax exemption certificate that the customer holds. 

exemptDescription

Description of the tax exemption certificate that the customer holds. 

exemptEffectiveDate

Date when the customer tax exemption starts. 

exemptExpirationDate

Date when the customer tax exemption expires.

exemptIssuingJurisdiction

Jurisdiction in which the customer tax exemption certificate was issued.

exemptStatus

Status of the account tax exemption. 

VATId

EU Value Added Tax ID.

 

Examples

HTTP/JSON request:

GET https://api.zuora.com/rest/v1/accounts/A00001115

JSON response:

{
    "basicInfo": {
        "id": "402892c74c9193cd014c91d35b0a0132",
        "name": "Test",
        "accountNumber": "A00000001",
        "notes": "",
        "status": "Active",
        "crmId": "",
        "batch": "Batch1",
        "invoiceTemplateId": null,
        "communicationProfileId": "303d186840e611df817c002185d714e1"
    },
    "billingAndPayment": {
        "billCycleDay": 1,
        "currency": "USD",
        "paymentTerm": "Net 30",
        "paymentGateway": "TestGateway"
    },
    "metrics": {
        "balance": 0,
        "totalInvoiceBalance": 0,
        "creditBalance": 0,
        "contractedMrr": -900
    },
    "billToContact": {
        "address1": "",
        "address2": "",
        "city": "",
        "country": null,
        "county": null,
        "fax": "",
        "firstName": "Test",
        "homePhone": "",
        "lastName": "Test",
        "mobilePhone": "",
        "nickname": "",
        "otherPhone": "",
        "otherPhoneType": null,
        "personalEmail": "",
        "state": "",
        "taxRegion": null,
        "workEmail": "Test@zuora.com",
        "workPhone": "",
        "zipCode": ""
    },
    "soldToContact": {
        "address1": "",
        "address2": "",
        "city": "",
        "country": null,
        "county": null,
        "fax": "",
        "firstName": "Test",
        "homePhone": "",
        "lastName": "Test",
        "mobilePhone": "",
        "nickname": "",
        "otherPhone": "",
        "otherPhoneType": null,
        "personalEmail": "",
        "state": "",
        "taxRegion": null,
        "workEmail": "Test@zuora.com",
        "workPhone": "",
        "zipCode": ""
    },
    "success": true
}

CURL request:

##
## get account information
##
echo
echo "=============Get Account ==========="
echo
curl -i -k -H "apiAccessKeyId:$USER_NAME" -H "apiSecretAccessKey:$PASSWORD" -H "Accept:application/json" -X GET $BASE_URL/v1/accounts/A00000001

JSON response:

{
  "metrics": {
    "totalInvoiceBalance": 0.0,
    "contractedMrr": 15983.17,
    "creditBalance": 0.0,
    "balance": 0.0
  },
  "basicInfo": {
    "communicationProfileId": "c4ebdd8098bc102dac4f001517641b94",
    "status": "Active",
    "invoiceTemplateId": null,
    "crmId": "",
    "name": "subscribeCallYan_1",
    "notes": "",
    "accountNumber": "A00001115",
    "id": "2c92a0f9391832b10139183e277a0042",
    "dfadsf__c": null
  },
  "soldToContact": {
    "zipCode": "95135",
    "taxRegion": "",
    "fax": "",
    "country": "United States",
    "county": "",
    "personalEmail": "personal_email@zbcloud.com",
    "nickname": "",
    "otherPhone": "",
    "otherPhoneType": "Work",
    "lastName": "Zou",
    "workEmail": "work_email@zbcloud.com",
    "homePhone": "",
    "state": "California",
    "firstName": "Cheng",
    "address2": "",
    "address1": "1400 Bridge Pkwy",
    "workPhone": "5555551212",
    "city": "San Jose",
    "mobilePhone": ""
  },
  "success": true,
  "billToContact": {
    "zipCode": "95135",
    "taxRegion": "",
    "fax": "",
    "country": "United States",
    "county": "",
    "personalEmail": "personal_email@zbcloud.com",
    "nickname": "",
    "otherPhone": "",
    "otherPhoneType": "Work",
    "lastName": "Zou",
    "workEmail": "work_email@zbcloud.com",
    "homePhone": "",
    "state": "California",
    "firstName": "Cheng",
    "address2": "",
    "address1": "1400 Bridge Pkwy",
    "workPhone": "5555551212",
    "city": "San Jose",
    "mobilePhone": ""
  },
  "billingAndPayment": {
    "billCycleDay": 1,
    "paymentTerm": "Due Upon Receipt",
    "currency": "USD"
  }
  "batch": "Australia"
}
Last modified
13:05, 17 Feb 2016

Tags

Classifications

(not set)