Pinlo Developer Docs

Overview

The Pinlo API lets you programmatically create, resolve, and manage location pins. Each pin is a verified GPS coordinate with a permanent shareable link (like pinlo.pk/hasan).

There are two API layers:

Authentication

Enterprise API endpoints require an API key passed in the X-API-Key header. You can generate API keys from your Pinlo dashboard after your access request is approved.

# Include your API key in every request
curl https://pinlo.pk/api/v1/pins \
  -H "X-API-Key: pnl_your_api_key_here"

Base URL

All API requests are made to:

https://pinlo.pk/api

Enterprise endpoints are prefixed with /v1. Public endpoints are at the root /api level.

Errors

The API returns standard HTTP status codes with JSON error bodies.

Error responses include a detail field:

{
  "detail": "Username already taken"
}

Rate Limits

API keys have per-day and per-month request limits based on your plan tier.

When you exceed limits, the API returns 429 Too Many Requests. Usage counters are visible in your dashboard and reset daily/monthly.

Create Pin

curl -X POST https://pinlo.pk/api/v1/pins \
  -H "X-API-Key: pnl_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "hasan-home",
    "name": "Hasan'\''s Home",
    "latitude": 24.8607,
    "longitude": 67.0011,
    "address": "Block 5, Clifton, Karachi",
    "notes": "Gate 3, ring doorbell twice",
    "category": "personal"
  }'

const response = await fetch("https://pinlo.pk/api/v1/pins", {
  method: "POST",
  headers: {
    "X-API-Key": "pnl_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    username: "hasan-home",
    name: "Hasan's Home",
    latitude: 24.8607,
    longitude: 67.0011,
    address: "Block 5, Clifton, Karachi",
    notes: "Gate 3, ring doorbell twice",
  }),
});

const pin = await response.json();
console.log(pin.url); // "https://pinlo.pk/hasan-home"

import requests

response = requests.post(
    "https://pinlo.pk/api/v1/pins",
    headers={"X-API-Key": "pnl_your_key"},
    json={
        "username": "hasan-home",
        "name": "Hasan's Home",
        "latitude": 24.8607,
        "longitude": 67.0011,
        "address": "Block 5, Clifton, Karachi",
        "notes": "Gate 3, ring doorbell twice",
    }
)

pin = response.json()
print(pin["url"])  # https://pinlo.pk/hasan-home

{
  "id": "a1b2c3d4-...",
  "pin_code": "PNL-X7K9M2",
  "username": "hasan-home",
  "name": "Hasan's Home",
  "latitude": 24.8607,
  "longitude": 67.0011,
  "address": "Block 5, Clifton, Karachi",
  "notes": "Gate 3, ring doorbell twice",
  "category": "personal",
  "is_active": true,
  "url": "https://pinlo.pk/hasan-home"
}

Resolve Pin

curl https://pinlo.pk/api/v1/pins/hasan-home \
  -H "X-API-Key: pnl_your_key"

{
  "username": "hasan-home",
  "name": "Hasan's Home",
  "latitude": 24.8607,
  "longitude": 67.0011,
  "address": "Block 5, Clifton, Karachi",
  "notes": "Gate 3, ring doorbell twice",
  "category": "personal",
  "confidence_score": 85,
  "is_verified": true,
  "access_level": "public",
  "url": "https://pinlo.pk/hasan-home"
}

List Pins

curl https://pinlo.pk/api/v1/pins \
  -H "X-API-Key: pnl_your_key"

[
  {
    "username": "hasan-home",
    "name": "Hasan's Home",
    "pin_code": "PNL-X7K9M2",
    "latitude": 24.8607,
    "longitude": 67.0011,
    "address": "Block 5, Clifton, Karachi",
    "category": "personal",
    "url": "https://pinlo.pk/hasan-home"
  },
  ...
]

Delete Pin

curl -X DELETE https://pinlo.pk/api/v1/pins/hasan-home \
  -H "X-API-Key: pnl_your_key"

{ "status": "disabled" }

Get Pin (Public)

# By username
curl https://pinlo.pk/api/pins/hasan-home

# By PNL code
curl https://pinlo.pk/api/pins/PNL-X7K9M2

# Protected pin (with access code)
curl https://pinlo.pk/api/pins/hasan-home?access_code=A3F1B9

Check Username

curl https://pinlo.pk/api/check/hasan-home

{
  "username": "hasan-home",
  "available": false
}

Track View

Track Navigation

Platform Stats

{
  "total_pins": 1247,
  "active_pins": 1183
}

Checkout Widget

Embed Pinlo's pin-drop widget in your e-commerce checkout. The customer either enters their existing Pinlo link or drops a new pin on a map — and you get verified GPS coordinates.

How it will work

Two integration paths for checkout:

The resolve flow works today with the Enterprise API. The embeddable widget for the create flow is coming soon.

Webhooks

Webhooks allow your server to receive real-time notifications when events happen on your pins.

Planned events

SDKs & Plugins

We're building official SDKs and plugins for common platforms:

In the meantime, the REST API works with any language or platform. The examples above in cURL, JavaScript, and Python cover everything you need to get started.