Skip to main content

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:

    NameTypeRequiredDescription
    usernameStringYesA 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.
    • 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",
    "username": "fb_user_id"
    },
    "instagram": {
    "display_name": "IG User",
    "social_images": "url_to_ig_image",
    "username": "ig_username"
    }
    // ... 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

ParameterTypeDescription
usernamestringRequired. 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"
},
"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:

    NameTypeRequiredDescription
    usernameStringYesThe unique identifier of the profile to delete.
  • Example Body:

    {
    "username": "user_id_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:

    NameTypeRequiredDescription
    usernameStringYesThe identifier for the user profile for which the JWT is being generated.
    redirect_urlStringNo(Optional) The URL to which the user will be redirected after linking their social account.
    logo_imageStringNo(Optional) A URL to a logo image to display on the linking page for branding purposes.
    redirect_button_textStringNo(Optional) The text to display on the redirect button after linking. Defaults to "Logout connection".
    platformsArrayNo(Optional) List of platforms to show for connection. Possible values: 'tiktok', 'instagram', 'linkedin', 'youtube' (not working, waiting for audit), 'facebook', 'x', 'threads'. Defaults to all supported platforms.
  • Example Body:

    {
    "username": "your_platform_user_id_123"
    }
  • Success Response (200 OK):

    {
    "access_url": "https://link.upload-post.com/connect?token=GENERATED_JWT_TOKEN",
    "success": true,
    "duration": "1h"
    }
    • 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 (typically "1h" for one hour).
  • 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 Success Response (200 OK):

    {
    "access_url": "https://app.upload-post.com/connect?token=GENERATED_JWT_TOKEN_STRING",
    "duration": "1h",
    "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.

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:

    NameTypeRequiredDescription
    profileStringNoThe 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).