Postman & Salesforce REST Web Services

Accessing an Apex web service from outside Salesforce

Postman logo

In this post we are going to talk about sending a request from a client that is outside Salesforce to an Apex web service in Salesforce. We are going to use the Postman client.

It might help if you already understand:

- Salesforce & Apex development

- API requests/responses

- Postman

Note: This post is very similar to the Salesforce REST API Integration w/OAuth article. There is some overlap, but we’ll be using Postman instead of another Salesforce org. And we’ll be hitting a custom endpoint, rather than a standard Salesforce REST API endpoint.

In order to callout to a Salesforce web service from Postman, or elsewhere, we will need a set of credentials and there needs to be a Connected App in our Salesforce org. We will need a username, password, client ID (Consumer Key), client secret (Consumer Secret).

We assume you have a username and password. If you don’t have a Connected App and the associated client ID and client secret, you will need to create one. You can read more on how to do that in Salesforce REST API Integration w/OAuth.

Now that we have our credentials ready, let’s open Postman. Before we can make a callout to our endpoint for the web service we need to authenticate and get an access token.

Enter POST for the method and the URL for your Salesforce instance. We’re using our production instance, so we’ll enter https://<yourinstance>.salesforce.com/services/oauth2/token (remember to replace <yourinstance> with your actual instance).

Postman with the HTTP method and URL

We don’t need to enter any headers so we move on to parameters. You can append these directly onto the URL or enter them under the Params tab. Postman is pretty cool, so it will interpret it correctly either way.

1. grant_type=password
2. client_id=<Consumer Key>
3. client_secret=<Consumer Secret>
4. username=<Salesforce username>
5. password=<Salesforce user security token>

Postman with parameters entered

We entered our parameters under the Params tab and we can see that Postman as appended them to the URL for us. Thanks Postman.

Now we hit Send. You may or may not get an error message, but we got the error: {“error”:”invalid_grant”,”error_description”:”authentication failure”}

Postman with invalid_grant error message

This can happen for a number of reasons and it is likely you will encounter this error. We had to work through it line-by-line.

You will have to prepend your Salesforce user password to the Salesforce user security token. If the user password is 123 and our user security token is XYZ then we have to enter 123XYZ as the value for the key of “password” (password=123XYZ). This fixed it for us. If, however, you continue to get this error you will need to troubleshoot it. Unfortunately, Salesforce is lazy and doesn’t provide additional information. Here are some things to double check:

1. The Connected App is created on the server (takes 2 - 10 minutes)
2. The Connected App is configured correctly
3. Client Id, client secret, username or password is correct/entered correctly
4. Prepend your Salesforce user password to the Salesforce user security token (as mentioned)

Once all your configurations and entries are correct Salesforce will return a response that includes the access token.

Postman with a response that contains the access token

Ok, the hard part is over and we have our access token we are ready to send a request to our Apex web service endpoint.

We have already created a web service in our Salesforce org. If you are not familiar with how to build one, you can use this tutorial: Apex Web Services

Our web service class is called Model2WebService. The endpoint is /Model2WebService/v1/*. We won’t cover what it does, because it isn’t relevant, but we will note that it is expecting one parameter called targetId which should have the value of either a Lead or Account ID.

Apex web service class named Model2WebService

In Postman we need to enter the following:

1. Method: POST
2. Header: Content-Type = application/json
3. Header: Authorization = Authorization: Bearer <access_token>
4. URL (web service endpoint): https://<yourinstance>.salesforce.com/services/apexrest/Model2WebService/v1

Postman with headers

Our web service is expecting a parameter: targetId. So we are going to enter that under the Params tab.

Postman with parameters

If your service is expecting addition headers, parameters or a request body, add those now. Then…

Hit Send.

Postman with response

Postman with status code

Status 201 Created! Great. And we received a response with the JSON specified by our web service, as expected. Our web service runs a class that makes an asynchronous API callout, so the only thing being returned is a basically meaningless response. You should expect a response containing the appropriate data for your service.

Web services and APIs have virtually endless differences and nuances, but this is a general outline of how to interact with a Salesforce Apex REST web service from a client hosted outside of your Salesforce instance.

We hope this helps!

Please feel free to leave kind comments, suggestions, corrections and better solutions!

Cat meme: Good job. Credit: memes.com