openapi: 3.1.0
info:
  title: Sender address
  version: 2.0.0
  description: Use the Sender Addresses API to retrieve sender addresses saved to your Sendcloud account. Sender addresses can be used when creating parcels via the API.
  contact:
    name: Sendcloud API Support
    url: https://www.sendcloud.dev
    email: contact@sendcloud.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://panel.sendcloud.sc/api/v2
    description: Production
tags:
  - name: Sender Address
paths:
  /user/addresses/sender:
    get:
      summary: Retrieve a list of sender addresses
      tags:
        - Sender Address
      responses:
        '200':
          description: List of sender addresses.
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  sender_addresses:
                    type: array
                    description: A list of the users configured sender addresses.
                    items:
                      $ref: '#/components/schemas/address'
              examples:
                RetrieveSenderAddresses:
                  summary: Retrieve a list of sender addresses
                  value:
                    sender_addresses:
                      - id: 2
                        company_name: French Company
                        contact_name: Marie Doe
                        email: info@sendcloud.fr
                        telephone: ''
                        street: Rue Villiers de l'Isle Adam
                        house_number: '33'
                        postal_box: ''
                        postal_code: '35000'
                        city: Rennes
                        country: FR
                        country_state: null
                        vat_number: NL123456789B01
                        eori_number: NL123456789
                        label: Sample label FR
                        brand_id: 1
                        signature_full_name: ''
                        signature_initials: ''
                      - id: 1
                        company_name: Sendcloud
                        contact_name: John Doe
                        email: johndoe@sendcloud.com
                        telephone: '+31626262626'
                        street: Bogert
                        house_number: '10'
                        postal_box: ''
                        postal_code: 5611 EM
                        city: Eindhoven
                        country: NL
                        country_state: null
                        vat_number: NL123456789B01
                        eori_number: NL123456789
                        label: Sample label NL
                        brand_id: 2
                        signature_full_name: John Doe
                        signature_initials: JD
      operationId: sc-public-v2-addresses-get-all_sender_addresses
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
      description: Returns a list of all the sender addresses which have been saved to your account.
      x-mint:
        href: /api/v2/sender-addresses/retrieve-a-list-of-sender-addresses
        content: |-
          <Warning>
            **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).
          </Warning>

          The response will include the `id` of each address, which you can include as a parameter when [creating parcels](/api/v2/parcels/create-a-parcel-or-parcels) or [looking up shipping methods](/api/v2/shipping-methods/retrieve-a-list-of-shipping-methods) via the API.
  /user/addresses/sender/{id}:
    parameters:
      - schema:
          type: integer
          example: 1234
        name: id
        in: path
        required: true
        description: The sender address unique identifier
    get:
      summary: Retrieve a sender address
      operationId: sc-public-v2-addresses-get-sender_address_by_id
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
      responses:
        '200':
          description: Sender address information.
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  sender_address:
                    $ref: '#/components/schemas/address'
              examples:
                RetrieveSenderAddress:
                  summary: A single sender address
                  value:
                    sender_address:
                      city: Eindhoven
                      company_name: Sendcloud
                      contact_name: John Doe
                      country: NL
                      country_state: null,
                      email: johndoe@sendcloud.com
                      house_number: '10'
                      id: 1
                      postal_box: ''
                      postal_code: 5611 EM
                      street: Stadhuisplein
                      telephone: '+31626262626'
                      vat_number: NL123456789B01
                      eori_number: NL123456789
                      brand_id: 2
                      label: Sample label
                      signature_full_name: John Doe
                      signature_initials: JD
        '404':
          description: Sender address not found
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - request
                      - message
                    properties:
                      code:
                        type: integer
                      request:
                        type: string
                        minLength: 1
                      message:
                        type: string
                        minLength: 1
                required:
                  - error
              examples:
                NotFound:
                  summary: Not Found
                  value:
                    error:
                      code: 404
                      request: api/v2/user/addresses/sender/12312312312
                      message: No sender address matches the given query.
      description: Retrieve information about a specific sender address saved to your account.
      x-mint:
        href: /api/v2/sender-addresses/retrieve-a-sender-address
        content: |-
          <Warning>
            **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).
          </Warning>

          A sender address `id` for use in this endpoint can be obtained from the [Retrieve a list of sender addresses](/api/v2/sender-addresses/retrieve-a-list-of-sender-addresses) endpoint.
      tags:
        - Sender Address
components:
  securitySchemes:
    HTTPBasicAuth:
      type: http
      description: Basic Authentication using API key and secrets is currently the main authentication mechanism.
      scheme: basic
    OAuth2ClientCreds:
      type: oauth2
      description: OAuth2 is a standardized protocol for authorization that allows users to share their private resources stored on one site with another site without having to provide their credentials. OAuth2 Client Credentials Grant workflow. This workflow is typically used for server-to-server interactions that require authorization to access specific resources.
      flows:
        clientCredentials:
          tokenUrl: https://account.sendcloud.com/oauth2/token/
          scopes:
            api: Default OAuth scope required to access Sendcloud API.
  schemas:
    address:
      title: Address Object
      type: object
      description: A Sendcloud address object
      properties:
        city:
          type: string
          maxLength: 30
        company_name:
          type: string
          maxLength: 50
        contact_name:
          type: string
          maxLength: 50
        country:
          type: string
          example: NL
          maxLength: 2
        country_state:
          type: string
          nullable: true
          maxLength: 10
        email:
          type: string
          maxLength: 254
          format: email
        house_number:
          type: string
          maxLength: 20
        id:
          type: integer
        postal_box:
          type: string
          maxLength: 12
        postal_code:
          type: string
          maxLength: 12
        street:
          type: string
          maxLength: 75
        telephone:
          type: string
          maxLength: 20
        vat_number:
          type: string
          maxLength: 20
        eori_number:
          type: string
          maxLength: 18
        brand_id:
          type: integer
        label:
          type: string
          maxLength: 30
          description: Label of the sender address.
        signature_full_name:
          type: string
          description: Full name that is used for the signature of this sender address.
        signature_initials:
          type: string
          description: Initials that are used for the signature of this sender address.