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. It's easy to determine whether you have administration privileges. In the Zuora application, if you can see the Administration Settings menu option (under the Settings menu in the upper right corner of the UI), 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:
- Performance Test:
<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:
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:
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.
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.
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.
This example uses the following fields and values:
<!-- 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>firstname.lastname@example.org</ns1:username> <ns1:password>17parRot8sox</ns1:password> </ns1:login> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
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>