# Custom Integrations (Petfinder App)

This tutorial covers how to build an app that facilitates pet adoption through a custom integration with the open-source API, Petfinder. Check out this tutorial if you want to learn more about:

* Creating custom integrations
* Querying external APIs
* Working with data pulled from external sources
* Displaying repeating elements

> 🚧 This is an advanced tutorial. It assumes comfort working with external integrations and HTTP requests, as well as familiarity with the contents of the tutorial, [Your First App (A Simple Form)](your-first-app-a-simple-form). If you haven't gone through that tutorial yet, we recommend you do so before proceeding.

**Here are the parts of the Airkit platform that you will be working with:**

* [Journey Builder](../studio/builder-bar/journey-builder): Starting the Journey
* [Console](../console/console): Configuring your integration
* [Settings](../studio/builder-bar/settings): Tying the integration to the Journey
* [Web Flows Builder](../studio/builder-bar/web-flows-builder): Creating the UI
* [Connections Builder](../studio/builder-bar/connections-builder): Querying the API and reformatting the data
* [Media Library](../studio/builder-bar/media-library): Uploading pictures to display in the UI
* [Variable Tree](../studio/variable-tree): Manage local variables

**For a demonstration how this application will work once we're finished, check out this video:**

\[block:embed] { "html": "\<iframe class="embedly-embed" src="//cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FEs\_SGNu9dt4%3Ffeature%3Doembed\&display\_name=YouTube\&url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DEs\_SGNu9dt4\&image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FEs\_SGNu9dt4%2Fhqdefault.jpg\&key=f2aa6fc3595946d0afc3d76cbbd25dc3\&type=text%2Fhtml\&schema=youtube" width="854" height="480" scrolling="no" title="YouTube embed" frameborder="0" allow="autoplay; fullscreen" allowfullscreen="true">", "url": "https://www.youtube.com/watch?v=Es\_SGNu9dt4\&feature=youtu.be", "title": "Petfinder Tutorial - DEMO", "favicon": "https://www.youtube.com/s/desktop/d4eb50c8/img/favicon.ico", "image": "https://i.ytimg.com/vi/Es\_SGNu9dt4/hqdefault.jpg", "provider": "youtube.com", "href": "https://www.youtube.com/watch?v=Es\_SGNu9dt4\&feature=youtu.be" } \[/block]

You will also be creating a free account with [https://www.petfinder.com/](https://www.petfinder.com/) as part of the process of integrating with their Petfinder API.

## Defining the App Journey

Create a new, blank app and open it in Studio for editing. This will land you in **Journey** Builder.

1. We're going to create a Journey that users access through a link. Drag the **Visit a Link** User Interaction to **Triggers**.

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-b696d65e57db1fb5f8cb19fe54cf05046458c69d%2Fcustom-integrations-pet-adoption-v182-0.png?alt=media)

2. In **Journey Steps**, under **Step 1 > Web Flow Starts**, click on **Add a Web Flow** and select **Create Blank**.

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-486cb6c2efe1bd1497986f2b07f0b74ba44649a4%2Fcustom-integrations-pet-adoption-v182-1.png?alt=media)

You've now set up an entry point for your application and defined a Web Flow for it to lead to! Be sure to save your progress before continuing.

## Setting up the Petfinder API

To integrate with the Petfinder API, you need to register an application and obtain the API key and Secret. To get an API key, you need to create a Petfinder account.

1. Create an account at [https://www.petfinder.com/user/login/](https://www.petfinder.com/user/login/)
2. Once logged in, go to www.petfinder.com/developers and complete the form with your app details.
3. Finally, click on **Get a key**.

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-5209d48c1159e4eb744d090c4596cfdf0776c14e%2Fcustom-integrations-pet-adoption-v182-2.png?alt=media)

Now your API Key and Secret are ready to be used to integrate your Petfinder account with your app.

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-7821bd4ba1dd3d9a289a710c78b081b7ef699894%2Fcustom-integrations-pet-adoption-v182-3.png?alt=media)

## Creating the Custom Integration

Now that you have the API Key and Secret, go back to the **Console** to establish your custom integration. We recommend doing so while keeping [Petfinder's reference documentation](https://www.petfinder.com/developers/v2/docs/) open, to keep the configuration details handy.

<details>

<summary>Why does the integration process require leaving the Studio and making changes in the Console?</summary>

\


Keeping track of integration credentials is done at the [Org](../administration/airkit-organizations)-level rather than within individual applications. Once a resource has been established, it can be used in all applications within the Organization.

This saves time in the long run: integrations only need to be established once, and the inherent standardization of the connections makes it easier to use external tools as a single source of truth within multiple Airkit apps.

</details>

1. Click on **Integrations** on the left side menu. Select **Custom Integrations** and click on **Create new.**

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-26d8d22cad95f159a9b233a32888bfb6dc599aaa%2Fcustom-integrations-pet-adoption-v182-4.png?alt=media)

2. A few fields will display for you to complete as follows:
   * Designate your integration with an intuitive name, such as "Petfinder integration".
   * Enter “petfinder-integration” under **Key**. This will be used to identify the integration.
   * Select **Custom Token** as the Authentication Type.
   * Under **Access Token Endpoint**, enter the following URL from Petfinder's API reference docs: [https://api.petfinder.com/v2/oauth2/token](https://api.petfinder.com/v2/oauth2/token)
   * Select **POST** under the **Access Token Verb**.

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-9613423ea7acc7aa46f82246b59f8991a605855e%2Fcustom-integrations-pet-adoption-v182-5.png?alt=media)

3. Under **Access Token Parameters**, click on the ‘+’ icon to define the following integration parameters:
   * grant\_type:

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-3554c6cafd90312552fcff31f793b36f18204e97%2Fcustom-integrations-pet-adoption-v182-6.png?alt=media)

* Client\_id (Set the Parameter Value to the **API Key** associated with your Petfinder Account):

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-12744a14a8f923ddceae674f966a5e2f15680a81%2Fcustom-integrations-pet-adoption-v182-7.png?alt=media)

* Client\_secret (Set the Parameter Value to the **Secret Key** associated with your Petfinder Account)):

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-194195f869c9dd2395d7473c112610ab9dbf3ca3%2Fcustom-integrations-pet-adoption-v182-8.png?alt=media)

4. Once the Parameters are set, complete these last three fields:
   * Choose **Header** as the Token Parameter Type.
   * Name the Token Parameter “Authorization”.
   * Enter "Bearer {token}" as the Parameter Value and click the **Create** button.

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-29504c14b60ea1ccf6a65702a52184ec1652cd10%2Fcustom-integrations-pet-adoption-v182-9.png?alt=media)

Now you can see Petfinder listed among your custom integrations.

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-b95e1533f75f907cda5c827dd5de836114bf2b15%2Fcustom-integrations-pet-adoption-v182-10.png?alt=media)

## Creating a Connected Account

After setting up the custom integration, you need to connect the integration to Airkit. This will surface the integration to your application and make it usable in apps.

1. Go **Integrations > Connected Accounts** and click on **Create new**. Define an intuitive account name (such as "Petfinder Integration") and select the Petfinder integration from the integration’s dropdown.

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-15d839b5087ceca93faa10e3b1c62707c6ba58a0%2Fcustom-integrations-pet-adoption-v182-11.png?alt=media)

2. Click on **Create** to connect the integration. It will show up in the list among your other connected accounts.

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-be8fa44f40facddf80b673743b312125e51af479%2Fcustom-integrations-pet-adoption-v182-12.png?alt=media)

## Connecting the Petfinder Integration to the Application

Once an integration with Petfinder has been established at the Org-level, re-open your pet adoption app in the **Studio** and toggle over to **Settings**.

1. Once in **Settings**, locate the **Integrations** section.
2. Click on the ‘+’ icon and select the Petfinder Integration as the adapater.

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-5265f7a7a322e7fe226a91e626568a74a92abdb2%2Fcustom-integrations-pet-adoption-v182-13.png?alt=media)

3. Under **Connected Account**, select the Petfinder Integration.

![](https://3088276961-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC6qMwMGWBgxnN70QsDuH%2Fuploads%2Fgit-blob-fd6829b70a8fe3c865cc1bfb5e3ff7cb409a45a0%2Fcustom-integrations-pet-adoption-v182-14.png?alt=media)

You've now integrated your pet adoption app with the Petfinder API! Save your progress, and get ready to incorporate some HTTP requests to the Petfinder API into your application flow.
