User Profiles API

These endpoints allow you to integrate Upload-Post directly into your platform by managing user profiles and generating secure tokens for account linking.

See the User Profile Integration Guide for a conceptual overview and workflow.

Authentication

All API requests require authentication using your API Key. Include it in the Authorization header for every request:

Authorization: Apikey YOUR_API_KEY

Replace YOUR_API_KEY with the actual API key provided to you.

User Profile Management

Manage user profiles within Upload-Post that correspond to users on your platform.

Endpoint

/api/uploadposts/users

Create User Profile

Creates a new profile linked to a user on your platform.

Method: POST
Headers:
- Authorization: Apikey YOUR_API_KEY
- Content-Type: application/json
Body Parameters:

Name Type Required Description
username String Yes A unique identifier for the user on your platform (e.g., your internal ID).

Name	Type	Required	Description
username	String	Yes	A unique identifier for the user on your platform (e.g., your internal ID).

Example Body:

{
  "username": "your_platform_user_id_123"
}

Success Response (201 Created):
```
{
  "profile": {
    "created_at": "Fri, 02 May 2025 21:43:14 GMT",
    "social_accounts": {
      "tiktok": ""
      // Other platforms will appear here as they are connected
    },
    "username": "your_platform_user_id_123"
  },
  "success": true
}
```
- profile: Contains details of the newly created profile.
  - created_at: Timestamp of profile creation.
  - social_accounts: Object showing connected accounts (initially empty or with placeholders).
  - username: The unique identifier provided.
- success: Indicates successful creation.
Error Responses:
- 400 Bad Request: Missing or invalid username.
- 401 Unauthorized: Invalid or missing API Key.
- 403 Forbidden: Profile limit reached for the current plan (error_code: PROFILE_LIMIT_REACHED).
- 409 Conflict: A profile with the provided username already exists.

Get User Profiles

Retrieves a list of all user profiles created under your API key.

Method: GET
Headers:
- Authorization: Apikey YOUR_API_KEY
Query Parameters: None

Success Response (200 OK):

{
    "limit": 10,
    "plan": "default",
    "profiles": [
        {
            "created_at": "2025-04-02T17:44:33.229755",
            "social_accounts": {
                "facebook": {
                    "display_name": "FB User",
                    "social_images": "url_to_fb_image"
                },
                "instagram": {
                    "display_name": "IG User",
                    "social_images": "url_to_ig_image"
                }
                // ... other connected platforms with their details
            },
            "username": "your_platform_user_id_1"
        },
        {
            "created_at": "Fri, 02 May 2025 21:43:14 GMT",
            "social_accounts": {
                "tiktok": "" // Example of a platform added but not yet connected
            },
            "username": "your_platform_user_id_2"
        }
    ],
    "success": true
}

limit: The maximum number of profiles allowed by the current plan.
plan: The subscription plan associated with the API key.
profiles: An array of user profile objects.
- created_at: Timestamp of profile creation.
- social_accounts: An object detailing connected social media accounts. Each key is the platform name (e.g., facebook, instagram, tiktok). The value can be an object with details (display_name, social_images, username) or an empty string/null if not fully connected.
- username: The unique identifier for the profile.
success: Indicates successful retrieval.

Error Responses:
- 401 Unauthorized: Invalid or missing API Key.

Get a Specific User Profile

Retrieves information for a single user profile using its username.

Method: GET
Endpoint: /api/uploadposts/users/{username}

Path Parameters

Parameter	Type	Description
`username`	string	Required. The username of the profile to retrieve.

Success Response (200 OK)

If the profile is found, the API will return a JSON object with the profile details.

{
    "success": true,
    "profile": {
        "created_at": "2023-10-27T10:00:00Z",
            "social_accounts": {
                "tiktok": {
                    "username": "tiktok_user_123",
                    "display_name": "User Display Name",
                    "social_images": "https://example.com/image.jpg"
                },
                "bluesky": {
                     "username": "user.bsky.social",
                     "display_name": "Bluesky User",
                     "social_images": "https://example.com/avatar.jpg"
                },
                "instagram": null
            },
        "username": "specific_profile_name"
    }
}

Error Response (404 Not Found)

If no profile is found with the specified username, the API will return:

{
    "success": false,
    "message": "Profile not found"
}

Delete User Profile

Deletes an existing user profile and its associated data (like social connections).

Method: DELETE
Headers:
- Authorization: Apikey YOUR_API_KEY
- Content-Type: application/json
Body Parameters:

Name Type Required Description
username String Yes The unique identifier of the profile to delete.
Example Body:
```
{
  "username": "user_id_to_delete"
}
```

Name	Type	Required	Description
username	String	Yes	The unique identifier of the profile to delete.

Success Response (200 OK):

{
  "message": "Perfil eliminado correctamente",
  "success": true
}

Error Responses:
- 400 Bad Request: Missing or invalid username.
- 401 Unauthorized: Invalid or missing API Key.
- 404 Not Found: No profile found with the provided username.

JWT Management

Generate and validate JWTs for the secure social account linking process.

Endpoint: Generate JWT URL

/api/uploadposts/users/generate-jwt

Generates a secure, single-use URL containing a JWT. Your user visits this URL to link their social media accounts.

Method: POST
Headers:
- Authorization: Apikey YOUR_API_KEY
- Content-Type: application/json

Body Parameters:

Name	Type	Required	Description
username	String	Yes	The identifier for the user profile for which the JWT is being generated.
redirect_url	String	No	(Optional) The URL to which the user will be redirected after linking their social account.
logo_image	String	No	(Optional) A URL to a logo image to display on the linking page for branding purposes.
redirect_button_text	String	No	(Optional) The text to display on the redirect button after linking. Defaults to "Logout connection".
connect_title	String	No	(Optional) Custom title text for the connection page. Defaults to "Connect Social Media Accounts".
connect_description	String	No	(Optional) Custom description text for the connection page. Defaults to "Connect your social media accounts to manage your posts.".
platforms	Array	No	(Optional) List of platforms to show for connection. Possible values: 'tiktok', 'instagram', 'linkedin', 'youtube' (not working, waiting for audit), 'facebook', 'x', 'threads', 'google_business'. Defaults to all supported platforms.
show_calendar	Boolean	No	(Optional) Whether to show the calendar view on the connection page. Defaults to `true`.
readonly_calendar	Boolean	No	(Optional) When `true`, shows only a read-only calendar view. The user cannot edit, delete, or create posts, and cannot connect or disconnect social accounts. Ideal for sharing a content calendar with end clients. Defaults to `false`.

Example Body:

{
  "username": "your_platform_user_id_123"
}

Success Response (200 OK):
```
{
  "access_url": "https://app.upload-post.com/connect?token=GENERATED_JWT_TOKEN",
  "success": true,
  "duration": "48h"
}
```
- access_url: The secure URL your user needs to visit. Redirect your user to this URL.
- success: Always true if the request was successful.
- duration: The validity period of the generated JWT (48 hours).

Example Request (curl):

curl -X POST https://api.upload-post.com/api/uploadposts/users/generate-jwt \
  -H "Authorization: Apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "your_platform_user_id_123"}'

Example Request with Calendar Disabled (curl):

curl -X POST https://api.upload-post.com/api/uploadposts/users/generate-jwt \
  -H "Authorization: Apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "your_platform_user_id_123", "show_calendar": false}'

Example Request with Read-Only Calendar for Clients (curl):

curl -X POST https://api.upload-post.com/api/uploadposts/users/generate-jwt \
  -H "Authorization: Apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "your_platform_user_id_123", "readonly_calendar": true, "logo_image": "https://youragency.com/logo.png", "connect_title": "Your Content Calendar"}'

This generates a link where the client only sees the calendar with scheduled posts (social channel, date/time, visual, text) but cannot edit anything or access other sections.

Example Success Response (200 OK):

{
  "access_url": "https://app.upload-post.com/connect?token=GENERATED_JWT_TOKEN_STRING",
  "duration": "48h",
  "success": true
}

Calendar Deep Link: If you want users to land directly on the shared calendar view, replace the path with /connect/calendar while keeping the token intact, e.g. https://app.upload-post.com/connect/calendar?token=GENERATED_JWT_TOKEN. The page will automatically fall back to /connect when the profile has show_calendar disabled. When readonly_calendar is true, the user is automatically redirected to the calendar view regardless of the URL path.
Error Responses:
- 400 Bad Request: Missing or invalid username.
- 401 Unauthorized: Invalid or missing API Key.
- 403 Forbidden: Profile exists but is blocked by plan limits (error_code: PROFILE_BLOCKED).
- 404 Not Found: No profile found with the provided username (error_code: PROFILE_NOT_FOUND).
Integration tip: If JWT generation returns 404, call GET /api/uploadposts/users first to confirm the profile exists and that profile creation did not fail due to plan limits.

Mobile OAuth Compatibility

When users open the connection page on a mobile device (iOS or Android), the operating system may intercept OAuth URLs (e.g. instagram.com, accounts.google.com) and open the corresponding native app instead of keeping the flow in the browser. Because native apps cannot handle the OAuth authorization URL, the connection fails.

Upload-Post automatically detects mobile browsers and routes OAuth redirects through a secure intermediate page (/api/uploadposts/oauth/bounce) that performs the redirect via JavaScript. This bypasses Universal Links (iOS) and App Links (Android) interception so the OAuth flow stays entirely in the mobile browser.

No action is required from API consumers — the mobile-safe redirect is applied automatically when the user accesses the access_url on a mobile device.

Endpoint: Validate JWT

/api/uploadposts/users/validate-jwt

(Optional) Allows you to validate a JWT token. The primary validation occurs automatically when the user accesses the access_url.

Method: POST
Headers:
- Authorization: Bearer YOUR_JWT_TOKEN
Body Parameters: None

Example Request (curl):

# Replace YOUR_JWT_TOKEN with the actual token string
curl -X POST https://api.upload-post.com/api/uploadposts/users/validate-jwt \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Success Response (200 OK - Valid Token): Returns the profile details associated with the token.
```
{
  "profile": {
    "social_accounts": {
      "tiktok": null,
      "instagram": "connected_account_details",
      // ... other platforms
    },
    "username": "your_platform_user_id_123"
  },
  "success": true
}
```
- profile: Contains details about the user profile linked to the token.
  - social_accounts: An object showing the connection status for various platforms (e.g., null if not connected, or details if connected).
  - username: The unique identifier provided when the profile was created.
- success: Indicates the token is valid.

Success Response (200 OK - Invalid Token):

{
  "isValid": false,
  "reason": "Token expired or invalid signature" // Example reason
}

Error Responses:
- 401 Unauthorized: Invalid, expired, or missing JWT token in the Authorization header.

Facebook Pages

Retrieve Facebook page IDs associated with user profiles to enable posting to Facebook pages.

Endpoint

/api/uploadposts/facebook/pages

Get Facebook Pages

Fetches Facebook page IDs associated with a profile. You can use this endpoint to connect and start posting on Facebook pages.

Method: GET
Headers:
- Authorization: Apikey YOUR_API_KEY
Query Parameters:

Name Type Required Description
profile String No The unique identifier of the profile. If not specified, returns all pages for your account.

Name	Type	Required	Description
profile	String	No	The unique identifier of the profile. If not specified, returns all pages for your account.

Example Request (curl):

curl 'https://api.upload-post.com/api/uploadposts/facebook/pages?profile=your_profile' \
  -H 'Authorization: Apikey YOUR_API_KEY'

Example Request (without profile parameter):

curl 'https://api.upload-post.com/api/uploadposts/facebook/pages' \
  -H 'Authorization: Apikey YOUR_API_KEY'

Success Response (200 OK):

{
  "pages": [
    {
      "page_id": "123456789",
      "page_name": "My Business Page",
      "profile": "your_platform_user_id_123"
    },
    {
      "page_id": "987654321", 
      "page_name": "Another Page",
      "profile": "your_platform_user_id_123"
    }
  ],
  "success": true
}

pages: Array of Facebook page objects associated with the profile(s).
- page_id: The Facebook page ID that can be used for posting.
- page_name: The display name of the Facebook page.
- profile: The profile identifier associated with this page.
success: Indicates successful retrieval.

Error Responses:
- 401 Unauthorized: Invalid or missing API Key.
- 404 Not Found: No profile found with the provided identifier (if profile parameter is specified).

Authentication​

User Profile Management​

Endpoint​

Create User Profile​

Get User Profiles​

Get a Specific User Profile​

Delete User Profile​

JWT Management​

Endpoint: Generate JWT URL​

Mobile OAuth Compatibility​

Endpoint: Validate JWT​

Facebook Pages​

Endpoint​

Get Facebook Pages​

Authentication

User Profile Management

Endpoint

Create User Profile

Get User Profiles

Get a Specific User Profile

Delete User Profile

JWT Management

Endpoint: Generate JWT URL

Mobile OAuth Compatibility

Endpoint: Validate JWT

Facebook Pages

Endpoint

Get Facebook Pages