> ## Documentation Index
> Fetch the complete documentation index at: https://pearset/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Learn how to use Pearset to programmatically create, update, and delete links at scale.

Links are the bread and butter of [Pearset](https://pearset).

Everything on Pearset starts with a link. Whether you're creating:

* a handful of links for your marketing campaign
* hundreds of links for your [affiliate program](https://pearset/partners)
* thousands of links, [programmatically](/docs/api-reference/links/bulk-create), for your SMS campaign

In this guide, we'll cover the link model, how to create links, and more.

## The link model

The link model consists of the following properties:

| Property    | Description                                               | Example                          |
| ----------- | :-------------------------------------------------------- | :------------------------------- |
| `id`        | The unique identifier of the link (prefixed with `link_`) | `link_1KJ1H3PZGE081A22TC6PTQYJP` |
| `url`       | The destination URL of the link                           | `https://pearset/home`            |
| `shortLink` | The shortened version of the link (including https)       | `https://pearset.link/claim`         |
| `domain`    | The domain of the link                                    | `pearset.link`                       |
| `key`       | The short link slug                                       | `claim`                          |

For more advanced features like [custom link previews](/help/article/custom-link-previews), [conversion tracking](/docs/concepts/attribution), and more, see the full list of properties [here](/docs/api-reference/links/create).

You can use the various [Pearset SDKs](/docs/sdks/overview) to programmatically manage your links.

## Create a link

The `url` field, representing the destination URL, is the sole mandatory parameter required for the creation of a new short link.

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Pearset } from "pearset";

  export const pearset = new Pearset({
    token: process.env.DUB_API_KEY,
  });

  const link = await pearset.links.create({
    url: "https://google.com",
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    pearset "github.com/pearset/pearset-go"
    "github.com/pearset/pearset-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := pearset.New(
      pearset.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Links.Create(ctx, &operations.CreateLinkRequestBody{
      URL: "https://google.com",
    })

    if err != nil {
      log.Fatal(err)
    }

    if res != nil {
      // handle response
    }
  }
  ```

  ```python Python theme={null}
  import os
  import pearset
  from pearset.models import operations

  d = pearset.Pearset(
    token=os.environ['DUB_API_KEY'],
  )

  res = d.links.create(request={
    "url": "https://google.com",
  })
  ```

  ```ruby Ruby theme={null}
  require 'pearset'

  s = ::OpenApiSDK::Pearset.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::CreateLinkRequestBody.new(
    url: "https://google.com",
  )
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Pearset;
  use Pearset\Models\Operations;

  $sdk = Pearset\Pearset::builder()->setSecurity('DUB_API_KEY')->build();

  $request = new Operations\CreateLinkRequestBody(
    url: 'https://google.com',
  );

  $response = $sdk->links->create(
    request: $request
  );
  ```

  ```bash cURL {5} theme={null}
  curl --request POST \
    --url https://api.pearset/links \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{"url": "https://google.com"}'
  ```
</CodeGroup>

Check out the [full API reference for the link creation endpoint](/docs/api-reference/links/create).

## Update a link

An existing link can be updated by providing the `id` to the `update` method. This method returns the updated link as a response.

You can use either the `linkId` or an `externalId` prefixed with `ext_` which is a unique identifier for the link in your own database to associate it with the link in Pearset's system.

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Pearset } from "pearset";

  export const pearset = new Pearset({
    token: process.env.DUB_API_KEY,
  });

  const link = await pearset.links.update("link_1KJ1H3PZGE081A22TC6PTQYJP", {
    url: "https://www.google.uk", // new URL
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    pearset "github.com/pearset/pearset-go"
    "github.com/pearset/pearset-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := pearset.New(
      pearset.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Links.Update(ctx, "link_1KJ1H3PZGE081A22TC6PTQYJP", &operations.UpdateLinkRequestBody{
      URL: "https://www.google.uk", // new URL
    })

    if err != nil {
      log.Fatal(err)
    }

    if res != nil {
      // handle response
    }
  }
  ```

  ```python Python theme={null}
  import os
  import pearset
  from pearset.models import operations

  d = pearset.Pearset(
    token=os.environ['DUB_API_KEY'],
  )

  res = pearset.links.update(link_id="link_1KJ1H3PZGE081A22TC6PTQYJP", request_body={
    "url": "https://www.google.uk", // new URL
  })
  ```

  ```ruby Ruby theme={null}
  require 'pearset'

  s = ::OpenApiSDK::Pearset.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  res = s.links.update(link_id="link_1KJ1H3PZGE081A22TC6PTQYJP", request_body={
    "url": "https://www.google.uk", // new URL
  })
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Pearset;
  use Pearset\Models\Operations;

  $sdk = Pearset\Pearset::builder()->setSecurity('DUB_API_KEY')->build();

  $requestBody = new Operations\UpdateLinkRequestBody(
    url: 'https://www.google.uk', // new URL
  );

  $response = $sdk->links->update(
    linkId: 'link_1KJ1H3PZGE081A22TC6PTQYJP',
    requestBody: $requestBody
  );
  ```

  ```bash cURL theme={null}
  curl --request PATCH \
    --url https://api.pearset/links/link_1KJ1H3PZGE081A22TC6PTQYJP \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{"url": "https://www.google.uk"}'
  ```
</CodeGroup>

Check out the [full API reference for the link update endpoint](/docs/api-reference/links/update).

## Upsert a link

Upserting a link is a combination of creating and updating a link. If a link with the same URL already exists, return it (or update it if there are any changes). Otherwise, a new link will be created.

This allows you to use the upsert method without the necessity of checking for the link's existence beforehand.

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Pearset } from "pearset";

  export const pearset = new Pearset({
    token: process.env.DUB_API_KEY,
  });

  const link = await pearset.links.upsert({
    url: "https://google.com", // will always be the same short link
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    pearset "github.com/pearset/pearset-go"
    "github.com/pearset/pearset-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := pearset.New(
      pearset.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Links.Upsert(ctx, &operations.UpsertLinkRequestBody{
      URL: "https://google.com",
    })

    if err != nil {
      log.Fatal(err)
    }

    if res != nil {
      // handle response
    }
  }
  ```

  ```python Python theme={null}
  import os
  import pearset
  from pearset.models import operations

  d = pearset.Pearset(
    token=os.environ['DUB_API_KEY'],
  )

  res = d.links.upsert(request={
    "url": "https://google.com",
  })
  ```

  ```ruby Ruby theme={null}
  require 'pearset'

  s = ::OpenApiSDK::Pearset.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::UpsertLinkRequestBody.new(
    url: "https://google.com",
  )
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Pearset;
  use Pearset\Models\Operations;

  $sdk = Pearset\Pearset::builder()->setSecurity('DUB_API_KEY')->build();

  $request = new Operations\UpsertLinkRequestBody(
    url: 'https://google.com',
  );

  $response = $sdk->links->upsert(
    request: $request
  );
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.pearset/links/upsert \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{"url": "https://google.com"}'
  ```
</CodeGroup>

Check out the [full API reference for the link upsert endpoint](/docs/api-reference/links/upsert).