Salesforce Docs Portal

Connect to SOAP-Based API

To use SOAP API, pass your username, password, and security token to the login() operation. When you do, the API returns information about your API user. It also provides a session ID, which you include in the header of each subsequent SOAP request that you issue. A session ID remains valid for 2 hours. After the session ID expires, call the login() operation again to obtain a new one.

Step 1: Obtain your security token

The Salesforce Platform requires you to provide a security token to authorize requests that you make to SOAP API. A security token is a string of text that is unique to your user. Later, when you call the login() operation, you append the security token to your password. If you don’t have a security token or you lost it, you can obtain one using the Salesforce web app.

  1. In Salesforce, click your profile icon in the top-right corner of the page, and then click Settings.
  2. Under My Personal Information, click Reset My Security Token.
  3. Click Reset Security Token.
  4. Check the email address that’s associated with your Salesforce account for a message from info@salesforcedevs.com. The email contains your new security token. The security token remains valid until you request a new one or until you change your password.

Step 2: Download the enterprise WSDL

A Web Services Description Language (WSDL) file describes the functionality of a web service such as an API. Salesforce provides two WSDLs: an Enterprise WSDL that reflects the exact configuration of your Salesforce org and a Partner WSDL that applies to all Salesforce orgs. You can download both WSDL files using the Salesforce web app.

  1. From Setup, in the Quick Find box, enter API.
  2. Under Integrations, click API.
  3. Under Enterprise WSDL, click Generate Enterprise WSDL.
  4. Click Generate.

note: In some web browsers, the contents of the WSDL are displayed in a new browser window. In this situation, right-click anywhere on the page, click Save page as, and then save the WSDL file.

Step 3: Load the WSDL into your client

The instructions for loading a WSDL into your web services client depend on which client you use. Consult the documentation for your client. These instructions describe using SoapUI.

  1. On the File menu, click New SOAP Project.
  2. On the New SOAP Project window, enter a name for the project.
  3. Next to Initial WSDL, click Browse.
  4. Locate the WSDL file that you downloaded earlier. Click Open, and then click OK.

SoapUI parses the WSDL file and generates a list of all available API operations.

Step 4: Use the login() method to obtain an authenticated session ID

After you obtain your security token and set up your SOAP client, you can issue a request to the login() operation to obtain your session ID.

  1. In your SOAP client, create a request that uses the login() operation.

  2. In the body of the SOAP request, delete the contents of the SOAP header, which is everything between <soapenv:Header> and </soapenv:Header>.

  3. Change the value of urn:username to the username of your API user.

  4. Change the value of urn:password to the password of your API user, and then paste your security token to the end of the password.

  5. Submit the SOAP request. If you entered the correct username and password, the response from the API resembles this example.

    <!--The URLs and IDs in this example are randomly generated and don't represent a security risk.--> 
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="urn:enterprise.soap.sforce.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <loginResponse>
      <result>
        <metadataServerUrl>https://login.salesforce.com/services/Soap/c/60.0/wRYO4cyiogGJuSu</metadataSezverUz1>
        <passwordExpired>false</passwordExpired>
        <sandbox>false</sandbox>
        <serverUrl>https://login.salesforce.com/services/Soap/c/60.0/wRYO4cyiogGJuSu</serverUrl>
        <sessionId>wRYO4cyiogGJuSu!AQEAOK23h7Ak_SyGTu_DfrbaObz12XP7MxGCmTTT2zKkKRAB_f4t8XkJ.5gSSO1C_xyRPnrq.Ak.qt81Pg4PMkuAhtw7frLz</sessionId>
        <userId>HQ7tfVfduzymohBchM</userId>
        <userInfo>
          <accessibilityMode>false</accessibilityMode>
          <currencySymbol>$</currencySymbol>
          <orgAttachmentFileSizeLimit>5242880</orgAttachmentFileSizeLimit>
          <orgDefaultCurrencyIsoCode>USD</orgDefaultCurrencyIsoCode>
          <orgDisallowHtmlAttachments> false</orgDisallowHtmlAttachments>
          <orgHasPersonAccounts>false</orgHasPersonAccounts>
          <organizationId>Bg2kLrUat1Tl1seqDj</organizationId>
          <organizationMultiCurrency>false</organizationMultiCurrency>
          <organizationName>DreamHouse Realty</organizationName>
          <profileId>3nOZ5jz8ULZgsn2z3</profileId>
          <roleId xsi:nil="true"/>
          <sessionSecondsValid>7200</sessionSecondsValid>
          <userDefaultCurrencyIsoCode xsi:nil="true"/>
          <userEmail>dangelo.cunningham@example.com</userEmail>
          <userFullName>D'Angelo Cunningham</userFullName>
          <userId>HQ7tfVfduzymohBchM</userId>
          <userLanguage>en_US</userLanguage>
          <userLocale>en_US</userLocale>
          <userName>dangelo.cunningham@example.com</userName>
          <userTimeZone>America/Los_Angeles</userTimeZone>
          <userType>Standard</userType>
          <userUiSkin>Theme3</userUiSkin>
        </userInfo>
      </result>
    </loginResponse>
  </soapenv:Body>
</soapenv:Envelope>

note: The URLs and IDs in this example are randomly generated and can’t be used to issue or authenticate URL requests.

  1. Copy the value between the <sessionId>...</sessionId> tags.

In subsequent requests that you issue to the API, add the session ID to the SOAP header.