# Profiles API Reference

The Profiles API allows you to retrieve and manage connected social media profiles. Profiles represent authenticated connections to social media platforms.

## Endpoints

| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/api/profiles` | List all profiles |
| `GET` | `/api/profiles/:id` | Get a single profile |
| `GET` | `/api/profiles/:id/placements` | List placements for a profile |
| `DELETE` | `/api/profiles/:id` | Delete/disconnect a profile |

## Profile object

A profile represents a connected social media account.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Unique profile identifier (id) |
| `name` | string | Display name of the connected account |
| `status` | string | Platform connection status: `active`, `expired`, `inactive` (might be disconnected or suspended on a platform) |
| `platform` | string | Platform identifier |
| `profile_group_id` | string | ID of the profile group this belongs to |
| `expires_at` | string\|null | ISO 8601 timestamp when the connection expires (if applicable) |
| `post_count` | integer | Number of posts made through this profile |
| `avatar_url` | string\|null | URL to the profile’s avatar image (resized, hosted by Postproxy). `null` if not yet downloaded |

### Platform values

| Platform | Account type |
| --- | --- |
| `facebook` | Facebook Page |
| `instagram` | Instagram Business/Creator Account |
| `tiktok` | TikTok Account |
| `linkedin` | LinkedIn Profile or Company Page |
| `youtube` | YouTube Channel |
| `twitter` | X (Twitter) Account |
| `threads` | Threads Account |
| `pinterest` | Pinterest Account |

## List profiles

GET`/api/profiles`

Retrieves all profiles in the current profile group.

### Query parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `profile_group_id` | string | No | - | Filter by profile group (id) |

### Example

```
curl -X GET "https://api.postproxy.dev/api/profiles" \
     -H "Authorization: Bearer YOUR_API_KEY"
```

### Response:
```
{
  "data": [
    {
      "id": "prof123abc",
      "name": "My Company Page",
      "platform": "facebook",
      "status": "active",
      "profile_group_id": "grp456xyz",
      "expires_at": null,
      "post_count": 42,
      "avatar_url": "https://cdn.postproxy.dev/uploads/avatar_prof123abc.jpg"
    },
    {
      "id": "prof789def",
      "name": "@mycompany",
      "platform": "instagram",
      "status": "expired",
      "profile_group_id": "grp456xyz",
      "expires_at": "2024-03-15T00:00:00.000Z",
      "post_count": 38,
      "avatar_url": "https://cdn.postproxy.dev/uploads/avatar_prof789def.jpg"
    },
    {
      "id": "prof321ghi",
      "name": "John Doe",
      "platform": "linkedin",
      "status": "inactive",
      "profile_group_id": "grp456xyz",
      "expires_at": null,
      "post_count": 15,
      "avatar_url": null
    },
    {
      "id": "prof654jkl",
      "name": "@mycompany",
      "platform": "twitter",
      "status": "active",
      "profile_group_id": "grp456xyz",
      "expires_at": null,
      "post_count": 127,
      "avatar_url": "https://cdn.postproxy.dev/uploads/avatar_prof654jkl.jpg"
    }
  ]
}
```

## Get profile

GET`/api/profiles/:id`

Retrieves a single profile by its ID.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Profile id |

### Response:
```
{
  "id": "prof123abc",
  "name": "My Company Page",
  "platform": "facebook",
  "status": "active",
  "profile_group_id": "grp456xyz",
  "expires_at": null,
  "post_count": 42,
  "avatar_url": "https://cdn.postproxy.dev/uploads/avatar_prof123abc.jpg"
}
```

## List placements

GET`/api/profiles/:id/placements`

Retrieves the available placements for a profile. For Facebook profiles, placements are business pages. For LinkedIn profiles, placements include the personal profile and organizations. For Pinterest profiles, placements are boards.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Profile id |

### Placement object

| Field | Type | Description |
| --- | --- | --- |
| `id` | string\|null | Platform-specific placement ID. `null` for personal profile (LinkedIn) |
| `name` | string | Display name of the placement |

### Example

```
curl -X GET "https://api.postproxy.dev/api/profiles/prof123abc/placements" \
     -H "Authorization: Bearer YOUR_API_KEY"
```

### Response:
```
{
  "data": [
    {
      "id": null,
      "name": "Personal Profile"
    },
    {
      "id": "108520199",
      "name": "Acme Marketing"
    },
    {
      "id": "110131347",
      "name": "Acme Labs"
    }
  ]
}
```

## Delete profile

DELETE`/api/profiles/:id`

Disconnects and removes a profile from the account. This does not affect posts already published through this profile.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Profile id |

### Example

```
curl -X DELETE "https://api.postproxy.dev/api/profiles/prof123abc" \
     -H "Authorization: Bearer YOUR_API_KEY"
```

### Response:
```
{
  "success": true
}
```

## Token expiration

Some platforms issue access tokens that expire. The `expires_at` field indicates when the connection will expire and require re-authentication.

| Behavior | Description |
| --- | --- |
| `expires_at: null` | Token does not expire or has a refresh token |
| `expires_at: "2024-..."` | Token expires at the specified time |

## Connecting new profiles

Profiles cannot be created directly via the API. To connect a new social media account:

1. Use the [Initialize Connection](/content/reference/profile-groups/#initialize-connection/index.html) endpoint to get an OAuth URL
2. Redirect the user to that URL to authenticate
3. User is redirected back to your `redirect_url` after authentication
4. The profile is automatically created and associated with the profile group

## Using profiles in posts

When creating posts, reference profiles by:

1. **Profile ID**: Use the `id` id directly
2. **Platform name**: Use the platform string (e.g., `"twitter"`) to automatically select the profile for that platform

```
{
  "profiles": ["prof123abc", "twitter", "linkedin"]
}
```

If multiple profiles exist for the same platform in a profile group, using the platform name selects the first one. Use the profile ID for explicit selection.