OAuth 2.0 Authentication Flow
#### Step 1: Generate Authorization URL
```javascript
// Redirect user to Pinterest authorization page
const authUrl = https://www.pinterest.com/oauth/?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&response_type=code&scope=boards:read,pins:read,user_accounts:read;
window.location.href = authUrl;
```
#### Step 2: Exchange Code for Access Token
```bash
# After user authorizes, exchange authorization code for access token
curl -X POST https://api.pinterest.com/v5/oauth/token \
--header "Authorization: Basic {BASE64_ENCODED_CLIENT_CREDENTIALS}" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code={AUTHORIZATION_CODE}" \
--data-urlencode "redirect_uri={REDIRECT_URI}"
```
Base64 Encoding Client Credentials:
```bash
# Encode client_id:client_secret
echo -n "your_client_id:your_client_secret" | base64
```
Response:
```json
{
"access_token": "pina_ABC123...",
"token_type": "bearer",
"expires_in": 2592000,
"refresh_token": "DEF456...",
"scope": "boards:read,pins:read,user_accounts:read"
}
```
Pin Management
#### Create a Pin
```bash
curl -X POST https://api.pinterest.com/v5/pins \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"link": "https://example.com/my-article",
"title": "My Amazing Pin Title",
"description": "Detailed description of the pin content",
"board_id": "123456789",
"media_source": {
"source_type": "image_url",
"url": "https://example.com/image.jpg"
}
}'
```
#### Get Pin Details
```bash
curl -X GET https://api.pinterest.com/v5/pins/{PIN_ID} \
-H "Authorization: Bearer {ACCESS_TOKEN}"
```
Response:
```json
{
"id": "987654321",
"created_at": "2025-01-15T10:30:00",
"link": "https://example.com/my-article",
"title": "My Amazing Pin Title",
"description": "Detailed description of the pin content",
"board_id": "123456789",
"media": {
"media_type": "image",
"images": {
"150x150": { "url": "...", "width": 150, "height": 150 },
"400x300": { "url": "...", "width": 400, "height": 300 },
"originals": { "url": "...", "width": 1200, "height": 800 }
}
}
}
```
#### Update a Pin
```bash
curl -X PATCH https://api.pinterest.com/v5/pins/{PIN_ID} \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"title": "Updated Pin Title",
"description": "Updated description",
"link": "https://example.com/updated-link"
}'
```
#### Delete a Pin
```bash
curl -X DELETE https://api.pinterest.com/v5/pins/{PIN_ID} \
-H "Authorization: Bearer {ACCESS_TOKEN}"
```
Board Management
#### Create a Board
```bash
curl -X POST https://api.pinterest.com/v5/boards \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"name": "My New Board",
"description": "A collection of my favorite ideas",
"privacy": "PUBLIC"
}'
```
Privacy Options: PUBLIC, PROTECTED, SECRET
#### List User's Boards
```bash
curl -X GET https://api.pinterest.com/v5/boards \
-H "Authorization: Bearer {ACCESS_TOKEN}"
```
#### Get Board Pins
```bash
curl -X GET https://api.pinterest.com/v5/boards/{BOARD_ID}/pins \
-H "Authorization: Bearer {ACCESS_TOKEN}"
```
User Account
#### Get Current User Account
```bash
curl -X GET https://api.pinterest.com/v5/user_account \
-H "Authorization: Bearer {ACCESS_TOKEN}"
```
Response:
```json
{
"account_type": "BUSINESS",
"id": "123456789",
"username": "myusername",
"website_url": "https://example.com",
"profile_image": "https://i.pinimg.com/...",
"follower_count": 1500,
"following_count": 320,
"board_count": 25,
"pin_count": 450
}
```
Analytics
#### Get Pin Analytics
```bash
curl -X GET "https://api.pinterest.com/v5/pins/{PIN_ID}/analytics?start_date=2025-01-01&end_date=2025-01-31&metric_types=IMPRESSION,SAVE,PIN_CLICK" \
-H "Authorization: Bearer {ACCESS_TOKEN}"
```
Available Metrics:
IMPRESSION - Number of times pin was shownSAVE - Number of times pin was savedPIN_CLICK - Number of clicks to pin destinationOUTBOUND_CLICK - Clicks to external websiteVIDEO_START - Video plays started
Response:
```json
{
"all": {
"daily_metrics": [
{
"date": "2025-01-01",
"data_status": "READY",
"metrics": {
"IMPRESSION": 1250,
"SAVE": 45,
"PIN_CLICK": 89
}
}
]
}
}
```
Error Handling
#### Common Error Response
```json
{
"code": 3,
"message": "Requested pin not found"
}
```
Common Error Codes:
1 - Invalid request parameters2 - Rate limit exceeded3 - Resource not found4 - Insufficient permissions8 - Invalid access token
#### Python Error Handling Example
```python
import requests
def create_pin(access_token, board_id, title, image_url):
url = "https://api.pinterest.com/v5/pins"
headers = {
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json"
}
data = {
"board_id": board_id,
"title": title,
"media_source": {
"source_type": "image_url",
"url": image_url
}
}
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
return response.json()
except requests.exceptions.HTTPError as e:
error_data = e.response.json()
print(f"Error {error_data.get('code')}: {error_data.get('message')}")
return None
except requests.exceptions.RequestException as e:
print(f"Request failed: {str(e)}")
return None
```
JavaScript/Node.js Integration
```javascript
// Pinterest API Client Example
class PinterestClient {
constructor(accessToken) {
this.accessToken = accessToken;
this.baseUrl = 'https://api.pinterest.com/v5';
}
async request(endpoint, options = {}) {
const url = ${this.baseUrl}${endpoint};
const headers = {
'Authorization': Bearer ${this.accessToken},
'Content-Type': 'application/json',
...options.headers
};
const response = await fetch(url, {
...options,
headers
});
if (!response.ok) {
const error = await response.json();
throw new Error(Pinterest API Error: ${error.message});
}
return response.json();
}
async createPin(boardId, title, imageUrl, description = '', link = '') {
return this.request('/pins', {
method: 'POST',
body: JSON.stringify({
board_id: boardId,
title: title,
description: description,
link: link,
media_source: {
source_type: 'image_url',
url: imageUrl
}
})
});
}
async getUserBoards() {
return this.request('/boards');
}
async getPinAnalytics(pinId, startDate, endDate) {
const params = new URLSearchParams({
start_date: startDate,
end_date: endDate,
metric_types: 'IMPRESSION,SAVE,PIN_CLICK'
});
return this.request(/pins/${pinId}/analytics?${params});
}
}
// Usage
const client = new PinterestClient('your_access_token');
const pin = await client.createPin('board_id', 'Pin Title', 'https://example.com/image.jpg');
```
|