GoFundMe Branding API

openapi: 3.2.0
info:
  title: GoFundMe Pro Branding API
  description: "<h1>GoFundMe Pro API</h1>\n<p>Welcome to the GoFundMe Pro API (2.0.0), a powerful toolset that empowers innovative and creative minds to engineer the world for good. This documentation walks through the API’s latest endpoints.</p>\n<p>GoFundMe Pro APIs are crafted around REST and the REST architectural style to provide developers with a stateless and language-­agnostic interface. The GoFundMe Pro API leverages HTTP verbs and response codes, OAuth2 authentication, and resource-­oriented URLs.</p>\n<p>Currently, the GoFundMe Pro API only supports JSON. All POST/PUT requests required a valid JSON object for the request body.</p>\n<h2>Errors</h2>\n<p>The GoFundMe Pro API leverages standard HTTP response status codes for it’s error responses. Error codes are:</p>\n<p><br /></p>\n<table border='1'>\n<tr>\n<th width='100px'>Error Code</th>\n<th>Meaning</th>\n</tr>\n<tr>\n<td>400</td>\n<td>Bad Request: The request was malformed or provided incorrect/incomplete/conflicting parameters. Check the response for more detailed messaging about why the request was incorrect. Do not repeat request.</td>\n</tr>\n<tr>\n<td>401</td>\n<td>Unauthorized: The API does not recognize the request as authorized. API access token may be missing or invalid.</td>\n</tr>\n<tr>\n<td>403</td>\n<td>Forbidden: The API recognizes the authorized API user, but the API user does not have correct permissions to satisfy the request.</td>\n</tr>\n<tr>\n<td>404</td>\n<td>Not Found: The resource requested does not exist or was not found.</td>\n</tr>\n<tr>\n<td>405</td>\n<td>Method Not Allowed: Some REST endpoints only accept a subset of valid REST HTTP verbs. This error is sent when an unsupported verb is requested.</td>\n</tr>\n<tr>\n<td>429</td>\n<td>Too Many Requests: The rate limit has been exceeded. See the <a href=\"#rate-limiting\">Rate Limiting</a> section for details on rate limits and response headers.</td>\n</tr>\n<tr>\n<td>500</td>\n<td>Error: The request was valid, but something failed on the server. Additional messages may be available.</td>\n</tr>\n<tr>\n<td>503</td>\n<td>Service Unavailable: The service is temporarily unavailable.</td>\n</tr>\n</table>\n<h2>Requests</h2>\n<h3>Authenticating Requests</h3>\n<p>Most API requests will need to be signed with an Access Token.</p>\n<p>Refer to the <a href=\"https://developers.gofundme.com/pro/overview/authentication\" target=\"_blank\" rel=\"noopener noreferrer\">Resource Documentation</a> for the specific call you are making to see if an access token is required for your request. See <a href=\"https://developers.gofundme.com/pro/tutorials/samples\" target=\"_blank\" rel=\"noopener noreferrer\">this page</a> for a demonstration of usage through a sample app. \n<h3>Filters</h3>\n<p>We can filter a collection based on a set of input parameters. To do so, we can modify the query string using the parameters listed below.</p>\n\n<table border='1'>\n<tr>\n<th>Parameter</th>\n<th>Type</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n\n<tr>\n<td>with</td>\n<td>string</td>\n<td>N/A</td>\n<td>This allows you to include nested related resource. For example, you could request a campaign along with the organization it belongs to and the designation it was allocated to. In this case, <code>with=organization,designation.</code></td>\n</tr>\n\n<tr>\n<td>per_page</td>\n<td>integer</td>\n<td>20</td>\n<td>Set the total number of resources returned per page (Maximum: 100).</td>\n</tr>\n\n<tr>\n<td>page</td>\n<td>integer</td>\n<td>1</td>\n<td>Page to return.</td>\n</tr>\n\n<tr>\n<td>sort</td>\n<td>string</td>\n<td>Depends on endpoint</td>\n<td>\nOrder the resources depending upon their attributes. Examples:\n<ul>\n<li><strong>created_at</strong>: oldest resource will come first</li>\n<li><strong>created_at:desc</strong>: newest resource will come first</li>\n<li><strong>last_name:asc,first_name:asc</strong>: order resources by last_name in alphabetical order. If same last_name, order by first_name in alphabetical order.</li>\n</ul>\n</td>\n</tr>\n\n<tr>\n<td>fields</td>\n<td>string</td>\n<td>Depends on endpoint</td>\n<td>List of resources attributes separated with comma. Narrow the list of attributes returned for each resource.</td>\n</tr>\n\n<tr>\n<td>filter</td>\n<td>string</td>\n<td>NULL</td>\n<td>\nAllow to filter the list of resources returned. Format is: <code>{association}.{attribute1}{operand}{value}</code> where: <ul>\n<li>association is the association if this is a nested filter (optional)</li>\n<li>operand is one of the following: <code><=, >=, <>, !=, =, <, or ></code>. Operand must be url encoded. (Note: if you are filtering on a boolean value, <code>true</code> can be expressed with <code>true</code> or <code>1</code>. Additionally, false can be expressed with <code>false</code> or <code>0</code>).</li>\n<li>If filtering on an association, ensure you include the nested resource using the ‘with’ parameter. with | string | NULL | This allows you to include a nested related resource. For example, you could request a collection of campaigns along with the organization they belong to and the designation they were allocated to. In this case, <code>with=organization,designation</code>.</li>\n</ul>\n</td>\n</tr>\n</table>\n\n<p>When filtering, the operand should be one of the following:</p>\n<p><code><=, >=, <>, !=, =, <, or ></code>. Operand must be url encoded. (Note: if you are filtering on a boolean value, <code>true</code> can be expressed with <code>true</code> or <code>1</code>. Additionally, <code>false</code> can be expressed with <code>false</code> or <code>0</code>).</p>\n<p>If filtering on an association, ensure you include the nested resource using the ‘with’ parameter. This allows you to include a nested related resource. For example, you could request a collection of campaigns along with the organization they belong to and the designation they were allocated to. In this case, <code>with=organization,designation</code>.</p>\n<p>Refer to the sample documentation for the specific call you are making to see which related resource can be fetched.</p>\n\n<h3>Date and Time Filtering</h3>\n<p>Unless otherwise noted, all Datetime attributes in API responses will be returned in an ISO8601 compliant format:</p>\n<><code>YYYY-MM-DDTHH:mm:ss.sssZ</code> (e.g. <code>2024-10-05T14:48:00.000Z</code>).</p>\n<h2 id=\"rate-limiting\">Rate Limiting</h2>\n<p>The GoFundMe Pro API implements rate limiting to ensure fair usage and maintain service quality for all users. Rate limits are applied on a per-application and per-user basis.</p>\n<h3>When Rate Limiting Applies</h3>\n<p>Rate limiting is applied to requests that meet the following conditions:</p>\n<ul>\n<li>The API application is <strong>not internal</strong> (external/third-party applications)</li>\n<li>The API application is associated to an Organization</li>\n</ul>\n<p>Internal applications are not subject to rate limiting.</p>\n<h3>Rate Limit Details</h3>\n<p>By default, the rate limit is:</p>\n<ul>\n<li><strong>1800 requests per minute</strong> per application</li>\n</ul>\n<p>Rate limits may be adjusted dynamically via flags for specific applications or users.</p>\n<h3>Rate Limit Headers</h3>\n<p>All API responses include the following headers to help you track your rate limit status:</p>\n<table border='1'>\n<tr>\n<th width='200px'>Header</th>\n<th>Description</th>\n</tr>\n<tr>\n<td><code>X-RateLimit-Limit</code></td>\n<td>The maximum number of requests allowed in the current time window</td>\n</tr>\n<tr>\n<td><code>X-RateLimit-Remaining</code></td>\n<td>The number of requests remaining in the current time window</td>\n</tr>\n<tr>\n<td><code>X-RateLimit-Reset</code></td>\n<td>Unix timestamp indicating when the rate limit window resets (only included when limit is exceeded)</td>\n</tr>\n<tr>\n<td><code>Retry-After</code></td>\n<td>Number of seconds to wait before retrying (only included in 429 responses)</td>\n</tr>\n</table>\n<h3>Handling Rate Limit Errors</h3>\n<p>When you exceed the rate limit, the API will return a <code>429 Too Many Requests</code> response with the following structure:</p>\n<pre><code>{\n  \"message\": \"Too Many Attempts.\",\n  \"retry_after\": 42\n}</code></pre>\n<p>The response will include the <code>Retry-After</code> header indicating how many seconds you should wait before making another request.</p>\n<h3>Best Practices</h3>\n<ul>\n<li>Monitor the <code>X-RateLimit-Remaining</code> header to track your usage</li>\n<li>Implement exponential backoff when you receive a 429 response</li>\n<li>Respect the <code>Retry-After</code> header value before retrying</li>\n<li>Cache responses when possible to reduce API calls</li>\n<li>Batch operations when the API supports it</li>\n</ul>"
  version: 2.0.0
servers:
- url: https://pro.gofundme.com/api/2.0
security:
- OAuth2Application: []
- OAuth2Member: []
tags:
- name: Branding
  description: "Organizations can have branding images and styles that will be applied to various areas of the GoFundMe Pro platform.\n Examples include changing the GoFundMe Pro logo to the organization logo, adding an organization background image to the GoFundMe Pro login page, etc."
paths:
  /organizations/{organization}/branding:
    put:
      tags:
      - Branding
      summary: updateOrganizationBranding
      description: Create/Update Organization Branding
      operationId: updateOrganizationBranding
      parameters:
      - name: organization
        in: path
        description: The Organization ID
        required: true
        schema:
          type: integer
          example: 82364
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/BrandingFillable'
              - $ref: '#/components/schemas/OrganizationBrandingFillable'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Branding'
                - $ref: '#/components/schemas/OrganizationBranding'
        '403':
          description: Requester is not authorized to perform action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
        '404':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundResponse'
      security:
      - OAuth2Member: []
components:
  schemas:
    ForbiddenResponse:
      title: Forbidden Response
      properties:
        error:
          description: Description of detected error in request
          type: string
          example: This action is unauthorized.
      type: object
    ResourceNotFoundResponse:
      title: Resource Not Found Response
      properties:
        error:
          description: Description of detected errors in request
          type: string
      type: object
    OrganizationBranding:
      title: Organization Branding
      type: object
      allOf:
      - $ref: '#/components/schemas/BrandingFillable'
      - properties:
          favicon:
            description: URL of favicon image; deprecated/replaced by favicon_asset_url
            type:
            - string
            - 'null'
            example: ''
          favicon_asset_id:
            description: Primary identifier of associated Asset representing favicon image
            type:
            - integer
            - 'null'
            example: 1145
          favicon_asset_url:
            description: URL of favicon image derived from associated Asset
            type:
            - string
            - 'null'
            example: https://www.image-url.com/favicon.png
          organization_id:
            description: Primary identifier of associated Organization
            type: integer
            example: 82364
        type: object
    BrandingFillable:
      title: Branding Fillable
      properties:
        background_color:
          description: Color of main background
          type:
          - string
          - 'null'
          example: '#FFFFFF'
        background_image_style:
          description: CSS for rendering background image
          type:
          - string
          - 'null'
          example: repeat
        header_color:
          description: Color of header
          type:
          - string
          - 'null'
          example: '#ABABAB'
        header_footer_color:
          description: Color of footer portion of header
          type:
          - string
          - 'null'
          example: '#CCCCCC'
        header_image_height:
          description: Height of header image in pixels
          type:
          - integer
          - 'null'
          example: 200
        header_image_style:
          description: CSS for rendering header image
          type:
          - string
          - 'null'
          example: repeat
        header_url:
          description: URL of location to which header image links
          type:
          - string
          - 'null'
          example: https://www.my-url.com/donate
        primary_color:
          description: Primary color
          type:
          - string
          - 'null'
          example: '#F0F0F0'
        secondary_color:
          description: Secondary color
          type:
          - string
          - 'null'
          example: '#000000'
        font_family:
          description: Font family
          type:
          - string
          - 'null'
          example: var(--classy-font__font-family--verdana)
      type: object
    Branding:
      title: Branding
      properties:
        background_color:
          description: Color of main background
          type:
          - string
          - 'null'
          example: '#FFFFFF'
        background_image:
          description: URL of background image; deprecated/replaced by background_image_asset_url
          type:
          - string
          - 'null'
          example: https://www.image-url.com/background.png
        background_image_asset_id:
          description: Primary identifier of associated Asset representing background image
          type:
          - integer
          - 'null'
          example: 1145
        background_image_asset_url:
          description: URL of background image derived from associated Asset
          type:
          - string
          - 'null'
          example: https://www.image-url.com/background.png
        background_image_style:
          description: CSS for rendering background image
          type:
          - string
          - 'null'
          example: repeat
        custom_script:
          description: Raw javascript to be stored
          type:
          - string
          - 'null'
          example: script
        header_background_image:
          description: URL of header background image; deprecated/replaced by header_background_image_asset_id
          type:
          - string
          - 'null'
          example: https://www.image-url.com/header_background.png
        header_background_image_asset_id:
          description: Primary identifier of associated Asset representing the header background image
          type:
          - integer
          - 'null'
          example: 1145
        header_background_image_asset_url:
          description: URL of header background image derived from associated Asset
          type:
          - string
          - 'null'
          example: https://www.image-url.com/background.png
        header_color:
          description: Color of header
          type:
          - string
          - 'null'
          example: '#ABABAB'
        header_footer_color:
          description: Color of footer portion of header
          type:
          - string
          - 'null'
          example: '#CCCCCC'
        header_image:
          description: URL of header image; deprecated/replaced by header_image_asset_url
          type:
          - string
          - 'null'
          example: https://www.image-url.com/header.png
        header_image_asset_id:
          description: Primary identifier of associated Asset representing header image
          type:
          - integer
          - 'null'
          example: 1145
        header_image_asset_url:
          description: URL of header image derived from associated Asset
          type:
          - string
          - 'null'
          example: https://www.image-url.com/header.png
        header_image_height:
          description: Height of header image in pixels
          type:
          - integer
          - 'null'
          example: 200
        header_image_style:
          description: CSS for rendering header image
          type:
          - string
          - 'null'
          example: repeat
        header_url:
          description: URL of location to which header image links
          type:
          - string
          - 'null'
          example: https://www.my-url.com/donate
        hero_image_asset_id:
          description: Primary identifier of associated Asset representing hero image
          type:
          - integer
          - 'null'
          example: 1145
        hero_image_asset_url:
          description: URL of hero image derived from associated Asset
          type:
          - string
          - 'null'
          example: https://www.image-url.com/hero.png
        hide_classy_logo:
          description: Indicator dictating whether or not GoFundMe Pro logo is displayed
          type:
          - boolean
          - 'null'
          example: false
        primary_color:
          description: Primary color
          type:
          - string
          - 'null'
          example: '#F0F0F0'
        secondary_color:
          description: Secondary color
          type:
          - string
          - 'null'
          example: '#000000'
        font_family:
          description: Font family
          type:
          - string
          - 'null'
          example: var(--classy-font__font-family--verdana)
      type: object
    OrganizationBrandingFillable:
      title: Organization Branding Fillable
      type: object
      allOf:
      - $ref: '#/components/schemas/BrandingFillable'
      - properties:
          favicon:
            description: URL of favicon image; deprecated/replaced by favicon_asset_url
            type:
            - string
            - 'null'
            example: ''
          favicon_asset_id:
            description: Primary identifier of associated Asset representing favicon image
            type:
            - integer
            - 'null'
            example: 1145
          favicon_asset_url:
            description: URL of favicon image derived from associated Asset
            type:
            - string
            - 'null'
            example: https://www.image-url.com/favicon.png
        type: object
  securitySchemes:
    OAuth2Application:
      type: oauth2
      description: OAuth bearer token for client application
      flows:
        clientCredentials:
          tokenUrl: /oauth2/auth
          refreshUrl: /oauth2/auth
          scopes:
            read: Read access
            write: Write access
    OAuth2Member:
      type: oauth2
      description: OAuth bearer token for client application with additional member context
      flows:
        password:
          tokenUrl: /oauth2/auth
          refreshUrl: /oauth2/auth
          scopes:
            read: Read access
            write: Write access