> ## Documentation Index
> Fetch the complete documentation index at: https://api-doc.fidly.be/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Relation

> Create a third party of the company: a business (`type: company`) or an individual
(`type: contact`).

The body carries the relation and nothing else. `type` selects which fields it accepts,
and cannot be changed afterwards. A company is identified by its `name`, a contact by its
`first_name` — sending a field the other type owns is refused rather than ignored.
`address` is required, and must at least carry the `country_code`.

A company whose `vat`, `identifier` or `electronic_address` already belongs to another
company of the same company is refused with `409 duplicate_relation`; pass
`?ignore_duplicate=true` to create it anyway.

In sandbox mode the body is validated exactly as in live mode but nothing is stored, so
the returned `id` is not resolvable.



## OpenAPI

````yaml /openapi.json post /relations
openapi: 3.1.0
info:
  title: Fidly API
  version: 1.0.0
servers:
  - url: https://api.fidly.be
    description: Production
security: []
paths:
  /relations:
    post:
      tags:
        - relations
      summary: Create Relation
      description: >-
        Create a third party of the company: a business (`type: company`) or an
        individual

        (`type: contact`).


        The body carries the relation and nothing else. `type` selects which
        fields it accepts,

        and cannot be changed afterwards. A company is identified by its `name`,
        a contact by its

        `first_name` — sending a field the other type owns is refused rather
        than ignored.

        `address` is required, and must at least carry the `country_code`.


        A company whose `vat`, `identifier` or `electronic_address` already
        belongs to another

        company of the same company is refused with `409 duplicate_relation`;
        pass

        `?ignore_duplicate=true` to create it anyway.


        In sandbox mode the body is validated exactly as in live mode but
        nothing is stored, so

        the returned `id` is not resolvable.
      operationId: create_relation_relations_post
      parameters:
        - name: ignore_duplicate
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            description: >-
              Goes through even when the result would give this company the same
              `vat`, `identifier` or `electronic_address` as another one
              (otherwise refused with `409 duplicate_relation`). Companies only:
              passing it on a contact is refused, since there is no such check
              to waive. Never stored.
            title: Ignore Duplicate
          description: >-
            Goes through even when the result would give this company the same
            `vat`, `identifier` or `electronic_address` as another one
            (otherwise refused with `409 duplicate_relation`). Companies only:
            passing it on a contact is refused, since there is no such check to
            waive. Never stored.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/CompanyRelationCreate'
                - $ref: '#/components/schemas/ContactRelationCreate'
              discriminator:
                propertyName: type
                mapping:
                  company:
                    $ref: '#/components/schemas/CompanyRelationCreate'
                  contact:
                    $ref: '#/components/schemas/ContactRelationCreate'
              title: Payload
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CompanyRelationOut'
                  - $ref: '#/components/schemas/ContactRelationOut'
                discriminator:
                  propertyName: type
                  mapping:
                    company:
                      $ref: '#/components/schemas/CompanyRelationOut'
                    contact:
                      $ref: '#/components/schemas/ContactRelationOut'
                title: Response Create Relation Relations Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    CompanyRelationCreate:
      properties:
        email:
          anyOf:
            - type: string
              maxLength: 245
            - type: 'null'
          title: Email
          description: Primary email address.
        phone:
          anyOf:
            - type: string
              maxLength: 45
            - type: 'null'
          title: Phone
          description: Phone number.
        language:
          type: string
          title: Language
          description: Preferred language, one of ['fr', 'en', 'nl', 'de'].
          default: en
        address:
          $ref: '#/components/schemas/AddressCreate'
          description: Postal address. Required.
        type:
          type: string
          const: company
          title: Type
          description: Selects the `company` relation type.
        name:
          type: string
          maxLength: 245
          minLength: 1
          title: Name
          description: Company name.
        vat:
          anyOf:
            - type: string
              maxLength: 45
            - type: 'null'
          title: Vat
          description: VAT number, prefixed with the ISO country code.
        identifier:
          anyOf:
            - type: string
              maxLength: 45
            - type: 'null'
          title: Identifier
          description: Legal registration / party identifier.
        electronic_address:
          anyOf:
            - type: string
              maxLength: 60
            - type: 'null'
          title: Electronic Address
          description: Electronic address used to send invoices over Peppol.
        is_customer:
          type: boolean
          title: Is Customer
          description: Whether this company is a customer.
          default: true
        is_supplier:
          type: boolean
          title: Is Supplier
          description: Whether this company is a supplier.
          default: true
      additionalProperties: false
      type: object
      required:
        - address
        - type
        - name
      title: CompanyRelationCreate
      description: >-
        A business third party to create. `name` identifies it and is required.


        The contact-only fields (`first_name`, `last_name`) are rejected: an
        individual is a

        relation of type `contact`.
    ContactRelationCreate:
      properties:
        email:
          anyOf:
            - type: string
              maxLength: 245
            - type: 'null'
          title: Email
          description: Primary email address.
        phone:
          anyOf:
            - type: string
              maxLength: 45
            - type: 'null'
          title: Phone
          description: Phone number.
        language:
          type: string
          title: Language
          description: Preferred language, one of ['fr', 'en', 'nl', 'de'].
          default: en
        address:
          $ref: '#/components/schemas/AddressCreate'
          description: Postal address. Required.
        type:
          type: string
          const: contact
          title: Type
          description: Selects the `contact` relation type.
        first_name:
          type: string
          maxLength: 245
          minLength: 1
          title: First Name
          description: First name.
        last_name:
          anyOf:
            - type: string
              maxLength: 245
            - type: 'null'
          title: Last Name
          description: Last name.
      additionalProperties: false
      type: object
      required:
        - address
        - type
        - first_name
      title: ContactRelationCreate
      description: >-
        An individual to create. `first_name` is required; `last_name` is
        optional.


        `name` is **not** accepted: a contact's display name is derived from
        `last_name` and

        `first_name`. So are the company-only fields (`vat`, `identifier`,

        `electronic_address`, `is_customer`, `is_supplier`), which belong to a
        `company`.
    CompanyRelationOut:
      properties:
        id:
          type: string
          title: Id
          description: Opaque unique identifier of the relation.
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Display name. Company name for `company`, full name for `contact`.
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: Primary email address.
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
          description: Phone number.
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
          description: Preferred language, one of ['fr', 'en', 'nl', 'de'].
        address:
          anyOf:
            - $ref: '#/components/schemas/AddressOut'
            - type: 'null'
          description: Postal address, if known.
        type:
          type: string
          const: company
          title: Type
          description: Relation type, always `company` here.
        vat:
          anyOf:
            - type: string
            - type: 'null'
          title: Vat
          description: VAT number, prefixed with the ISO country code.
        identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Identifier
          description: Legal registration / party identifier.
        electronic_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Electronic Address
          description: Electronic address used to send invoices over Peppol.
        is_customer:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Customer
          description: '`true` if this company is a customer.'
        is_supplier:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Supplier
          description: '`true` if this company is a supplier.'
      additionalProperties: true
      type: object
      required:
        - id
        - type
      title: CompanyRelationOut
      description: >-
        A business third party. Carries the fields an individual has no
        equivalent of

        (`vat`, `identifier`, `electronic_address`, `is_customer`,
        `is_supplier`), and none of

        the contact-only ones — `first_name`/`last_name` are simply absent from
        the response.
    ContactRelationOut:
      properties:
        id:
          type: string
          title: Id
          description: Opaque unique identifier of the relation.
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Display name. Company name for `company`, full name for `contact`.
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: Primary email address.
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
          description: Phone number.
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
          description: Preferred language, one of ['fr', 'en', 'nl', 'de'].
        address:
          anyOf:
            - $ref: '#/components/schemas/AddressOut'
            - type: 'null'
          description: Postal address, if known.
        type:
          type: string
          const: contact
          title: Type
          description: Relation type, always `contact` here.
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
          description: First name.
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
          description: Last name.
      additionalProperties: true
      type: object
      required:
        - id
        - type
      title: ContactRelationOut
      description: >-
        An individual. `name` is derived from `last_name` + `first_name` and is
        read-only;

        the company-only fields (`vat`, `identifier`, `electronic_address`,
        `is_customer`,

        `is_supplier`) are absent from the response.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AddressCreate:
      properties:
        country_code:
          type: string
          title: Country Code
          description: >-
            Country of the relation (must be an ISO 3166-1 alpha-2 country code,
            e.g. 'BE').
        street:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Street
          description: Street name.
        street_number:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Street Number
          description: Street/house number. Requires `street`.
        street2:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Street2
          description: Additional address line.
        postal_code:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Postal Code
          description: Postal/ZIP code.
        city:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: City
          description: City.
        province:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Province
          description: 'Free text: province, state or region.'
      additionalProperties: false
      type: object
      required:
        - country_code
      title: AddressCreate
      description: >-
        The address of a relation being created. `country_code` is required — a
        relation is

        always located somewhere, and the country drives the VAT and Peppol
        handling downstream.


        `street_number` may only be given together with `street`: a house number
        on its own does

        not identify anything.
    AddressOut:
      properties:
        street:
          anyOf:
            - type: string
            - type: 'null'
          title: Street
          description: Street name.
        street_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Street Number
          description: Street/house number.
        street2:
          anyOf:
            - type: string
            - type: 'null'
          title: Street2
          description: Additional address line.
        postal_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Postal Code
          description: Postal/ZIP code.
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
          description: City.
        province:
          anyOf:
            - type: string
            - type: 'null'
          title: Province
          description: Province, state or region.
        country_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Country Code
          description: ISO 3166-1 alpha-2 country code (e.g. `BE`).
      type: object
      title: AddressOut
      description: >-
        Postal address of a relation. The object itself is `null` when none is
        stored.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````