Log in to the SOAP API

Last updated
Save as PDF

Your first step before making any SOAP API calls is to log in as an API user. Use the login() call to establish your session and get you a ID for the session. Use that session ID for your subsequent API calls during your session.

Do you have an API User Account?

Do you have an API user account? If not, then someone with administration privileges can set it up for you. To determine whether you have administration privileges, log in to the Zuora application and click your username in the upper right corner of the UI. If you can see the Administration menu option, you have administrative privileges.

Follow this quick procedure to set up your API user account.

If an API user account is used to log in to the UI, it becomes subject to periodic forced password expirations. This automatic security feature may eventually cause API authentication failures that can be hard to diagnose. For this reason, it is suggested that the API user account is never used to log in to the UI.

Send a login Call Request

Send a login() request to one of the following endpoints:

Production: https://www.zuora.com/apps/services/a/<wsdl version>
Sandbox: https://apisandbox.zuora.com/apps/services/a/<wsdl version>
Performance Test: https://pt1.zuora.com/apps/services/a/<wsdl version>

The <wsdl version> denotes the API or WSDL version that you are using, such as 68.0.

The login() call requires the following fields in the order they are listed:

username
password

Use your API login credentials, not your credentials to log in to the Zuora application.

The username must come before the password. If you reverse the order, then you receive the following error: Unexpected subelement username

Establishing a Session

When you send a login() request to your tenant, a session is established for you, and you receive a response that includes a unique ID for your session. Use this session ID in subsequent API calls during your session. The session ID is good for the duration specified in Administration Settings > Security Policies > Session timeout. Once the ID expires, you must send a new login() request to continue making SOAP calls.

See How do I prevent session tokens from expiring in the API for more information.

Receiving a Session ID

The login() call is successful when you receive a response that includes your session ID.

If the call fails, you will receive one of the following errors:

LoginFault
This error means that there is a mistake in your user name and password combination. Check both your user name and your password, then try again.
UnexpectedErrorFault
This error means that something happened during the call that interfered with your call being properly sent. Try the call again.

Both of these errors are faults, which are are fatal, call-level errors. When a fault occurs, nothing is processed because the entire call was invalid. Often the problem is that the login credentials were incorrect or there was a server error.

Examples

The example request and response demonstrate a login() call and response. The example query demonstrates using the session ID in your subsequent API calls.

See How do I capture SOAP API Requests and Responses for more information.

Example Request

This example uses the following fields and values:

username: luciaclavijo@example.com
password: 17parRot8sox

<!-- sample login call -->
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns1="http://api.zuora.com/">
    <SOAP-ENV:Body>
        <ns1:login>
            <ns1:username>luciaclavijo@example.com</ns1:username>
            <ns1:password>17parRot8sox</ns1:password>
        </ns1:login>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example Response

This example sends you the session ID, LiUBQF ... ugxg2jJuCA==, which you need to use for your subsequent API calls during this session. This example session ID is a truncated example of a real session ID: your session ID is substantially longer.

<!-- sample login response -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns1:loginResponse xmlns:ns1="http://api.zuora.com/">
            <ns1:result>
                <ns1:Session>LiUBQF...ugxg2jJuCA==</ns1:Session>
                <ns1:ServerUrl>https://api.zuora.com/apps/services/a/26.0</ns1:ServerUrl>
            </ns1:result>
        </ns1:loginResponse>
    </soapenv:Body>
</soapenv:Envelope>

Example Subsequent API Call

This particular example call is a query. Notice the session ID. You need to pass the session ID from the login() response for every call that you make during your session.

<!-- sample API query -->
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns1="http://api.zuora.com/">
    <SOAP-ENV:Header>
        <ns1:SessionHeader>
            <ns1:session>LiUBQF...ugxg2jJuCA==</ns1:session>
        </ns1:SessionHeader>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <ns1:query>
            <ns1:queryString>select id from account</ns1:queryString>
        </ns1:query>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>